This project provides a template for an angular project setup with webpack. It started as a companion of ng-jspm-template, with the primary purpose to provide an almost identical codebase and feature set compared to its brother to make it easier to figure out which template fits better to the daily requirements of development with angular.
I did not have enough time to keep this project up to date with the current angular development (esp. not in terms of features) for quite a while now, so I decided to officially stop maintaining it and put the repository in an archived state. Feel free to base your own project on it or use parts of it for other purposes.
To start using this template, you might either
-
pick the latest release
-
use something like degit for scaffolding
-
clone the repository directly for the most recent features and updates:
git clone https://github.com/DorianGrey/ng-webpack-template.git
You need to install a node.js version >= 8.9, since this project uses ES2015 language features, and we only support node versions from the current active LTS upwards. Things might work for earlier versions, but we do not provide any official support for this.
For users of nvm, we're providing a .nvmrc
file, so that you only need to execute:
nvm install
nvm use
We strongly recommend to use nvm (or any other node version manager of your choice).
This version currently favors to use yarn for faster dependency management. To install it, just run
npm install -g yarn
Alternatively, you might use npm
, as long as its version is 5.x or higher. There is an engine restriction in this projects package.json
to enforce this. The primary intent is to get a proper package-lock.json
as counterpart to yarn.lock
to lock your dependency versions. Just replace the yarn
part of the commands listed below with npm
resp. npm run
if you decide against yarn
.
The intended project structure, how to work with it and possibly extend it is documented in the docs folder.
- General structure
- The application state and how to extend it
- Development configuration
- Build configuration
- Integration and usage of the service worker
Even if we always attempt to avoid breaking changes, there are a couple of situations where this is not possible. For these cases, corresponding migration guides will be provided. The already existing ones are listed below.
- Update from < 12.0.0 to >= 12.0.0 (12.0.0 release): Guide
- Update from < 18.0.0 to >= 18.0.0 (18.0.0 release): Guide
- Update from < 19.0.0 to >= 19.0.0 (19.0.0 release): Guide
Just run
yarn start
which will fire up a development server (webpack-serve) using webpack's DLL feature up-front to speed up everything, and provide HMR functionality. The latter is based on ngrx/store. The server will be available on localhost:9987
by default (the URL will be copied to your clipboard as well. If you need to access the server via its public ip, just use yarn start:local
instead.
For configuring you development environment, check out the development configuration docs.
E2E-testing is currently not included in the default setup. This might change in the future, but for the moment you will have to setup tools like protractor or cypress on your own.
This project uses jest for unit testing. It includes both the test runner and framework. If you are not familiar with it yet, just have a look at its docs - should be simple enough. Just note that we're using the BDD
structure variant with describe
, beforeAll
, beforeEach
, it
etc. which should be quite familiar in case you have used jasmine
or mocha
before.
The setup is based on jest-preset-angular. In case you have to modify it for your particular purpose, you can change the global mocks in config/jest/jestGlobalMocks.ts
, the test setup config/jest/testSetup.ts
and jest
itself via jest.config.js
. If you are facing any problems, take a look at the troubleshooting guide.
The tasks below are pre-defined for testing.
Command | Effect |
---|---|
test | Starts the test runner in watch mode. Suitable for quick TDD, but not for explicit debugging or coverage reports. |
test:debug | Starts the test environment in a debug-compatible (i.e. inspectable) mode. Please have a look at the node inspector docs for instructions how to use it. If you are using VSCode, you might use the provided launch task instead of this command. |
test:ci | Starts the test runner in a CI optimized mode. Ignores caches and creates a coverage report. |
Generated reports are stored in the test-results
directory like, containing:
junit
contains a xunit compatible report. Compatible with most report tools used by CI systems.coverage
contains coverage reports inlcov
,json
,html
andcobertura
formats. The reporters in use can be configured in thejest.config.js
via thecoverageReporters
key.
Production builds are by default created using:
- AoT compilation
- Terser as code minifier
- build-optimizer for getting rid of additional dead / non-required code (esp. decorators).
- A service worker for improved PWA capabilities.
Optionally, you might:
- Disable the build optimizer. Though it already received a lot of work and fixes and should thus be production ready, it still has some glitches, so you might want this.
- In case AoT does not work: Disable it.
These options might be suitable for a particular situation while being problematic in another.
The AoT version is using the @ngtools/webpack plugin. Please keep an eye on the list of issues marked as related to it in case you're facing any errors.
Beware: The whole AoT processing currently enforces rather strict rules (see a rather good explanation here) on how not only your own code has to be written, but also the code of the libraries you are using. While I'd strongly recommend to head this way if it is possible in any way, esp. the latter restriction might screw up this plan.
The tables below will provide a full overview of the relevant commands.
Note that each build tasks will invoke the test
task (includes linting, generating the translations and executing the unit-tests) before the real build.
In addition to the regular build, every production build will also generate a bundle size analyze report in HTML and JSON format (powered by webpack-bundle-analyzer). It can be found in the buildStats
dir once the build task completes. Please keep in mind that it will be overwritten in every cycle.
The build can be configured in two ways:
- Statically in the
config/build.config.js
file. - Dynamically by adding options through the command line. Just use
yarn build -- --[your-option]=[your-option-value]
. You might override every entry, while every not provided parameter will fall back to the default. Options are evaluated using yargs.
See the build configuration documentation for details.
The preconfigured tasks are listed below.
Command | Effect |
---|---|
yarn build |
Creates a producton bundle, by default in the build folder. Utilizes AoT compilation and build-optimizer. |
yarn build:no-bo |
Creates a producton bundle, by default in the build folder. Utilizes AoT compilation, but not the build optimizer. |
yarn build:no-service-worker |
Creates a producton bundle, by default in the build folder. Utilizes AoT compilation and build optimizer, but does not generate a service worker file. |
The result of the build process can be served via the yarn serve
command. Note that if you changed the outputDir
option, you will have to provide it here as well, since the serve
script accesses your build configuration.
Command | Effect |
---|---|
yarn format |
Formats the code manually using prettier . While formatting is already applied automatically on commit creation or update, it might be useful to run this manually in some cases. |
yarn lint |
Runs both script and style linter manually on the code. This task is executed in a similar way when trying to create a commit. |
yarn inspect [mode] [other options] |
Provides an inspection of the webpack config constructed via webpack-chain . The first parameter is expected to be the target mode: dll for the development DLLs, dev or development ) for dev mode, prod or production for build mode. All other parameters can be provided as usual for the start and build tasks. |