angular-cli/docs/documentation/build.md

ng build

Overview

ng build compiles the application into an output directory.

Creating a build

ng build

The build artifacts will be stored in the dist/ directory.

All commands that build or serve your project, ng build/serve/e2e, will delete the output directory (dist/ by default). This can be disabled via the --no-delete-output-path (or --delete-output-path=false) flag.

Build Targets and Environment Files

ng build can specify both a build target (--target=production or --target=development) and an environment file to be used with that build (--environment=dev or --environment=prod). By default, the development build target and environment are used.

The mapping used to determine which environment file is used can be found in .angular-cli.json:

"environmentSource": "environments/environment.ts",
"environments": {
  "dev": "environments/environment.ts",
  "prod": "environments/environment.prod.ts"
}

These options also apply to the serve command. If you do not pass a value for environment, it will default to dev for development and prod for production.

# these are equivalent
ng build --target=production --environment=prod
ng build --prod --env=prod
ng build --prod
# and so are these
ng build --target=development --environment=dev
ng build --dev --e=dev
ng build --dev
ng build

You can also add your own env files other than dev and prod by doing the following:

• create a src/environments/environment.NAME.ts
• add { "NAME": 'src/environments/environment.NAME.ts' } to the apps[0].environments object in .angular-cli.json
• use them via the --env=NAME flag on the build/serve commands.

Base tag handling in index.html

When building you can modify base tag (<base href="/">) in your index.html with --base-href your-url option.

# Sets base tag href to /myUrl/ in your index.html
ng build --base-href /myUrl/
ng build --bh /myUrl/

Bundling & Tree-Shaking

All builds make use of bundling and limited tree-shaking, while --prod builds also run limited dead code elimination via UglifyJS.

--dev vs --prod builds

Both --dev/--target=development and --prod/--target=production are 'meta' flags, that set other flags. If you do not specify either you will get the --dev defaults.

Flag	--dev	--prod
--aot	false	true
--environment	dev	prod
--output-hashing	media	all
--sourcemaps	true	false
--extract-css	false	true
--named-chunks	true	false
--build-optimizer	false	true with AOT and Angular 5

--prod also sets the following non-flaggable settings:

• Adds service worker if configured in .angular-cli.json.
• Replaces process.env.NODE_ENV in modules with the production value (this is needed for some libraries, like react).
• Runs UglifyJS on the code.

--build-optimizer and --vendor-chunk

When using Build Optimizer the vendor chunk will be disabled by default. You can override this with --vendor-chunk=true.

Total bundle sizes with Build Optimizer are smaller if there is no separate vendor chunk because having vendor code in the same chunk as app code makes it possible for Uglify to remove more unused code.

CSS resources

Resources in CSS, such as images and fonts, will be copied over automatically as part of a build. If a resource is less than 10kb it will also be inlined.

You'll see these resources be outputted and fingerprinted at the root of dist/.

Service Worker

There is experimental service worker support for production builds available in the CLI. To enable it, run the following commands:

npm install @angular/service-worker --save
ng set apps.0.serviceWorker=true

On --prod builds a service worker manifest will be created and loaded automatically. Remember to disable the service worker while developing to avoid stale code.

Note: service worker support is experimental and subject to change.

ES2015 support

To build in ES2015 mode, edit ./tsconfig.json to use "target": "es2015" (instead of es5).

This will cause application TypeScript and Uglify be output as ES2015, and third party libraries to be loaded through the es2015 entry in package.json if available.

Be aware that JIT does not support ES2015 and so you should build/serve your app with --aot. See https://github.com/angular/angular-cli/issues/7797 for details.

Options

prod

--prod

Flag to set configuration to "prod".

configuration

--configuration (alias: -c)

Specify the configuration to use.

main

--main

The name of the main entry-point file.

polyfills

--polyfills

The name of the polyfills file.

ts-config

--ts-config

The name of the TypeScript configuration file.

optimization

--optimization

Defines the optimization level of the build.

output-path

--output-path

Path where output will be placed.

aot

--aot

Build using Ahead of Time compilation.

source-map

--source-map

Output sourcemaps.

eval-source-map

--eval-source-map

Output in-file eval sourcemaps.

vendor-chunk

--vendor-chunk

Use a separate bundle containing only vendor libraries.

common-chunk

--common-chunk

Use a separate bundle containing code used across multiple bundles.

base-href

--base-href

Base url for the application being built.

deploy-url

--deploy-url

URL where files will be deployed.

verbose

--verbose

Adds more details to output logging.

progress

--progress

Log progress to the console while building.

i18n-file

--i18n-file

Localization file to use for i18n.

i18n-format

--i18n-format

Format of the localization file specified with --i18n-file.

i18n-locale

--i18n-locale

Locale to use for i18n.

i18n-missing-translation

--i18n-missing-translation

How to handle missing translations for i18n.

extract-css

--extract-css

Extract css from global styles onto css files instead of js ones.

watch

--watch

Run build when files change.

output-hashing

--output-hashing

Define the output filename cache-busting hashing mode.

poll

--poll

Enable and define the file watching poll time period in milliseconds.

delete-output-path

--delete-output-path

Delete the output path before building.

preserve-symlinks

--preserve-symlinks

Do not use the real path when resolving modules.

extract-licenses

--extract-licenses

Extract all licenses in a separate file, in the case of production builds only.

show-circular-dependencies

--show-circular-dependencies

Show circular dependency warnings on builds.

build-optimizer

--build-optimizer

Enables @angular-devkit/build-optimizer optimizations when using the 'aot' option.

named-chunks

--named-chunks

Use file name for lazy loaded chunks.

subresource-integrity

--subresource-integrity

Enables the use of subresource integrity validation.

service-worker

--service-worker

Generates a service worker config for production builds.

ngsw-config-path

--ngsw-config-path

Path to ngsw-config.json.

skip-app-shell

--skip-app-shell

Flag to prevent building an app shell.

index

--index

The name of the index HTML file.

stats-json

--stats-json

Generates a 'stats.json' file which can be analyzed using tools such as: #webpack-bundle-analyzer' or https: //webpack.github.io/analyse.

fork-type-checker

--fork-type-checker

Run the TypeScript type checker in a forked process.