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
jsonfile (./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 withgulp v4andwebpack v3.
You can find the project documentation here.
You can view the live app at http://ng-seed.fulls1z3.com.
- Prerequisites
- Getting started
- Directory structure
- Configuring
ng-seed/universal - External stylesheets
- Contributing
- License
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.
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]
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.
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.
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
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.
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).
If you want to file a bug, contribute some code, or improve documentation, please read up on the following contribution guidelines:
The MIT License (MIT)
Copyright (c) 2018 Burak Tasci