ng-seed/universal

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:

• Providing a seed project using the Angular framework.
• Using the modern UI components of Angular Material.
• Dynamic responsive layouts via flex-layout.
• Ready-to-go build system using gulp and Webpack to work with TypeScript.
• Managing the type definitions using @types.
• angular-webpack-config as configuration preset for Webpack.
• The Dll Bundle and Hard Source plugins for lightning-fast development builds.
• Hot Module Replacement with Webpack and webpack-hot-middleware.
• Adjustable build configuration via json file (./tools/build/build-config.json).
• Development, staging and production modes.
• Performing AoT compilation for rapid page loads on staging/production builds (using @ngtools/webpack).
• Minifying the production builds using UglifyJS Webpack Plugin.
• Both inline and external SCSS compilation.
• stylelint-config-standard as configuration preset for stylelint and custom rules to standardize stylesheets.
• Transferring server responses on client bootstrap to prevent app flickering with native TransferState`.
• Deferring initialization of modules via Lazy loading.
• Uses ngrx/store for state management.
• Uses ngx-config for configuration management.
• Uses ngx-auth for basic JWT-based authentication (w/Universal support).
• Uses ngx-cache for application-wide caching.
• Uses ngx-translate for i18n support.
• Uses ngx-meta for SEO (title, meta tags, and Open Graph tags for social sharing).
• Uses ngx-i18n-router for localized routes.
• Uses ngx-perfect-scrollbar for scrollbars.
• Vendor-agnostic analytics via angulartics2.
• Unit tests with Jest, including code coverage.
• End-to-end (integration) tests with Nightmare.
• Seamless integration with CircleCI continuous integration and delivery platform.
• angular-tslint-rules as configuration preset for TSLint and codelyzer.

Built with Angular v6.x.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
• Getting started
  • Installation
  • Setting up upstream repository
  • Building
• Directory structure
• Configuring ng-seed/universal
• External stylesheets
• Contributing
• License

Prerequisites

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

Also, please ensure that you are using Typescript v2.6.x 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:

• Issue guidelines
• Contributing guidelines
• Coding rules
• Change log

Thanks to

• JetBrains, for their support to this open source project with free WebStorm licenses.

License

The MIT License (MIT)

Copyright (c) 2018 Burak Tasci