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

--extract-licenses Extract all licenses in a separate file, in the case of production builds only. --i18n-file Localization file to use for i18n. --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.

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.

Options

aot

--aot default value: false

Build using Ahead of Time compilation.

app

--app (aliases: -a)

Specifies app name or index to use.

base-href

--base-href (aliases: -bh)

Base url for the application being built.

deploy-url

--deploy-url (aliases: -d)

URL where files will be deployed.

environment

--environment (aliases: -e)

Defines the build environment.

extract-css

--extract-css (aliases: -ec)

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

i18n-file

--i18n-file

Localization file to use for i18n.

i18n-format

--i18n-format

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

locale

--locale

Locale to use for i18n.

missing-translation

--missing-translation

How to handle missing translations for i18n.

Values: error, warning, ignore

output-hashing

--output-hashing (aliases: -oh)

Define the output filename cache-busting hashing mode.

Values: none, all, media, bundles

output-path

--output-path (aliases: -op)

Path where output will be placed.

delete-output-path

--delete-output-path (aliases: -dop) default value: true

Delete the output-path directory.

poll

--poll

Enable and define the file watching poll time period (milliseconds).

progress

--progress (aliases: -pr) default value: true

Log progress to the console while building.

sourcemap

--sourcemap (aliases: -sm, sourcemaps)

Output sourcemaps.

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.

target

--target (aliases: -t, -dev, -prod) default value: development

Defines the build target.

vendor-chunk

--vendor-chunk (aliases: -vc) default value: true

Use a separate bundle containing only vendor libraries.

common-chunk

--common-chunk (aliases: -cc) default value: true

Use a separate bundle containing code used across multiple bundles.

verbose

--verbose (aliases: -v) default value: false

Adds more details to output logging.

watch

--watch (aliases: -w)

Run build when files change.

show-circular-dependencies

--show-circular-dependencies (aliases: -scd)

Show circular dependency warnings on builds.

build-optimizer

--build-optimizer

Enables @angular-devkit/build-optimizer optimizations when using `--aot`.

named-chunks

--named-chunks (aliases: -nc)

Use file name for lazy loaded chunks.

bundle-dependencies

--bundle-dependencies

In a server build, state whether `all` or `none` dependencies should be bundles in the output.