Skip to content

Latest commit

 

History

History
267 lines (225 loc) · 12.2 KB

README.md

File metadata and controls

267 lines (225 loc) · 12.2 KB
Raw

ng-seed/universal

CircleCI coverage Conventional Commits Greenkeeper badge Angular Style Guide

Please support this project by simply putting a Github star. Share this library with friends on Twitter and everywhere else you can.

ng-seed/universal is a seed project for Angular Universal apps following the common patterns and best practices in file and application organization, providing the following features:

Built with Angular v4.3.x, bundled with gulp v4 and webpack v3.

You can find the project documentation here.

You can view the live app at http://ng-seed.fulls1z3.com.

Table of contents:

Prerequisites

Packages in this seed project depend on @angular v4.3.x. Older versions contain outdated dependencies, might produce errors.

Also, please ensure that you are using Typescript v2.3.4 or higher.

Getting started

Installation

You can install ng-seed/universal by simply forking the repo:

# clone the repo
$ git clone https://github.com/ng-seed/universal.git [your-project-name]
$ cd [your-project-name]

Setting up upstream repository

Once you have cloned the repo, you can follow these steps to allow sync changes made in this repo with your fork:

# set up `origin`
$ git remote set-url origin [your-fork-repo]

# set up `upstream` to sync future changes
$ git remote add upstream https://github.com/ng-seed/universal.git

# verify the upstream repo specified for your fork
$ git remote -v
origin    https://github.com/YOUR_USERNAME/[your-fork-repo].git (fetch)
origin    https://github.com/YOUR_USERNAME/[your-fork-repo].git (push)
upstream  https://github.com/ng-seed/universal.git (fetch)
upstream  https://github.com/ng-seed/universal.git (push)

# initial push for the fork
$ git push

Now, you can create a new directory (ex: src/client/app/shared) to build your codebase out, while benefiting from the client framework located at the src/client/app/framework directory.

In order to merge the latest upstream changes, simply follow:

# fetch the latest upstream
$ git fetch upstream

# merge the upstream changes
$ git merge upstream/master

then handle any conflicts, and go on with building your app.

Building

These are the scripts to lint, test and build this seed project:

# use `yarn` to install the dependencies
$ yarn

# clean artifacts & DLL cache
$ npm run clean

# run tslint
$ npm run lint

# run unit tests
$ npm test

# run e2e tests
$ npm run e2e

# dev build (lean Angular / Angular Universal)
$ npm run build:spa-dev
# OR
$ npm run build:universal-dev

# stage build (lean Angular / Angular Universal)
$ npm run build:spa-stage
# OR
$ npm run build:universal-stage

# prod build (lean Angular / Angular Universal)
$ npm run build:spa-prod
# OR
$ npm run build:universal-prod

# start the server (lean Angular)
$ npm run serve:spa

# start the server (lean Angular w/HMR support)
$ npm run serve:spa-hmr

# start the server (Angular Universal)
$ npm run serve

# watch mode (build, and then HMR and test watch)
$ npm run serve:watch

Navigate to http://localhost:1337 for lean Angular (client-side rendering) and http://localhost:8000 for Angular Universal (server-side rendering) in your browser.

Directory structure

We use the component approach in this seed project, which is a standard for developing Angular apps and also a great way to ensure maintainable code by encapsulation of our behavior logic.

A component is basically a self contained app usually in a single file or a directory with each concern as a file: style, template, specs, and component class.

As an old convention, we use the + prefix for lazy-loaded modules. Please keep in mind that it does nor change the router behavior, neither makes the directory unworkable. It's just a handy method to identify lazy-loaded modules by having a straight look at the directory structure.

universal/
 ├──.cache/                         * cache directory for ngx-cache
 ├──.circleci/
 |   └──config.yml                  * CircleCI config
 ├──.github/                        * issue & pr templates
 ├──.server/                        * dev server, output directory to extract server bundles
 ├──coverage/                       * test coverage reports
 ├──node_modules/                   * dependencies
 ├──public/                         * output directory to extract client bundles
 |
 ├──src/
 |   ├──client/                     * client code
 |   |   ├──app/
 |   |   |   ├──components/         * components (USE HERE)
 |   |   |   |   ├──some-module/    * some module (as an example)
 |   |   |   |   └──+lazy-module/   * some LAZY module (attn to the `+` prefix for lazy-loaded modules)
 |   |   |   └──framework/          * client framework
 |   |   └──assets/                 * static assets (scss, img, json, etc.)
 |   └──server/                     * server code
 |
 ├──tools/
 |   ├──build/                      * build config and scripts (gulp, webpack, etc.)
 |   ├──config/                     * config files for static-assets (stylelint, postcss, etc.)
 |   └──test/                       * test config
 |
 ├──.gitignore                      * GIT settings
 ├──.jshintrc                       * jshint config
 ├──CHANGELOG.md                    * change log
 ├──CODE_OF_CONDUCT.md              * code of conduct
 ├──CONTRIBUTING.md                 * contributing info
 ├──gulpfile.js                     * gulp entry point
 ├──LICENSE                         * software license
 ├──package.json                    * deps management
 ├──README.md                       * project information
 ├──test-report.xml                 * JUNIT test results
 ├──tsconfig.json                   * typescript config
 ├──tsconfig.spec.json              * typescript config (for unit/e2e tests)
 ├──tslint.json                     * tslint config
 └──yarn.lock                       * deps lockfile

Configuring ng-seed/universal

Most of the configuration is done via ./tools/build/build-config.json, where you can customize host name, port numbers, and output directories for your app.

External stylesheets

Any stylesheets (SCSS) placed in the src/client/assets/scss directory and imported into your project will automatically be compiled into an external .css file and embedded in your staging/production builds.

All other stylesheets (SCSS) located below src/client/app will be extracted into the generated bundle (inline).

Contributing

If you want to file a bug, contribute some code, or improve documentation, please read up on the following contribution guidelines:

License

The MIT License (MIT)

Copyright (c) 2017 Burak Tasci