From 7d6db009e98ea64357fb04a4693dad091237a9f0 Mon Sep 17 00:00:00 2001 From: Alan Agius Date: Fri, 12 Mar 2021 08:14:30 +0100 Subject: [PATCH] docs: update docs to reflect production mode by default (#41173) In CLI version 12, we introduced the concept of production builds by default. With this change we update the documentation to reflect the changes. More information about the change can be found https://github.com/angular/angular-cli/pull/20128 PR Close #41173 --- aio/content/guide/app-shell.md | 13 ++++++++++--- aio/content/guide/build.md | 2 +- aio/content/guide/creating-libraries.md | 8 ++++---- aio/content/guide/deployment.md | 17 +++++++++-------- aio/content/guide/glossary.md | 2 +- aio/content/guide/i18n.md | 2 +- aio/content/guide/service-worker-config.md | 2 +- .../guide/service-worker-getting-started.md | 4 ++-- aio/content/guide/workspace-config.md | 8 +++++--- aio/content/start/start-deployment.md | 4 ++-- 10 files changed, 36 insertions(+), 26 deletions(-) diff --git a/aio/content/guide/app-shell.md b/aio/content/guide/app-shell.md index 82fef8ac23..1cd0f86f3b 100644 --- a/aio/content/guide/app-shell.md +++ b/aio/content/guide/app-shell.md @@ -31,12 +31,16 @@ After running this command you will notice that the `angular.json` configuration "server": { "builder": "@angular-devkit/build-angular:server", + "defaultConfiguration": "production", "options": { "outputPath": "dist/my-app/server", "main": "src/main.server.ts", "tsConfig": "tsconfig.server.json" }, "configurations": { + "development": { + "outputHashing": "none", + }, "production": { "outputHashing": "media", "fileReplacements": [ @@ -52,12 +56,15 @@ After running this command you will notice that the `angular.json` configuration }, "app-shell": { "builder": "@angular-devkit/build-angular:app-shell", + "defaultConfiguration": "production", "options": { - "browserTarget": "my-app:build", - "serverTarget": "my-app:server", "route": "shell" }, "configurations": { + "development": { + "browserTarget": "my-app:build:development", + "serverTarget": "my-app:server:development", + }, "production": { "browserTarget": "my-app:build:production", "serverTarget": "my-app:server:production" @@ -71,7 +78,7 @@ After running this command you will notice that the `angular.json` configuration Use the CLI to build the `app-shell` target. -ng run my-app:app-shell +ng run my-app:app-shell:development Or to use the production configuration. diff --git a/aio/content/guide/build.md b/aio/content/guide/build.md index a98cb22a87..a871bff5b0 100644 --- a/aio/content/guide/build.md +++ b/aio/content/guide/build.md @@ -117,7 +117,7 @@ For example: ... ``` -This means that when you build your production configuration (using `ng build --prod` or `ng build --configuration=production`), the `src/environments/environment.ts` file is replaced with the target-specific version of the file, `src/environments/environment.prod.ts`. +This means that when you build your production configuration with `ng build --configuration production`, the `src/environments/environment.ts` file is replaced with the target-specific version of the file, `src/environments/environment.prod.ts`. You can add additional configurations as required. To add a staging environment, create a copy of `src/environments/environment.ts` called `src/environments/environment.staging.ts`, then add a `staging` configuration to `angular.json`: diff --git a/aio/content/guide/creating-libraries.md b/aio/content/guide/creating-libraries.md index 40125f8ca4..22c7127fa8 100644 --- a/aio/content/guide/creating-libraries.md +++ b/aio/content/guide/creating-libraries.md @@ -45,13 +45,13 @@ When you generate a new library, the workspace configuration file, `angular.json You can build, test, and lint the project with CLI commands: - ng build my-lib + ng build my-lib --configuration development ng test my-lib ng lint my-lib Notice that the configured builder for the project is different from the default builder for app projects. -This builder, among other things, ensures that the library is always built with the [AOT compiler](guide/aot-compiler), without the need to specify the `--prod` flag. +This builder, among other things, ensures that the library is always built with the [AOT compiler](guide/aot-compiler). To make library code reusable you must define a public API for it. This "user layer" defines what is available to consumers of your library. A user of your library should be able to access public functionality (such as NgModules, service providers and general utility functions) through a single import path. @@ -118,10 +118,10 @@ To learn more, see [Schematics Overview](guide/schematics) and [Schematics for Use the Angular CLI and the npm package manager to build and publish your library as an npm package. -Before publishing a library to NPM, build it using the `--prod` flag which will use the older compiler and runtime known as View Engine instead of Ivy. +Before publishing a library to NPM, build it using the `production` configuration which uses the older compiler and runtime known as View Engine instead of Ivy. -ng build my-lib --prod +ng build my-lib cd dist/my-lib npm publish diff --git a/aio/content/guide/deployment.md b/aio/content/guide/deployment.md index acdfc3e5b0..366329f195 100644 --- a/aio/content/guide/deployment.md +++ b/aio/content/guide/deployment.md @@ -68,7 +68,7 @@ ng deploy The command is interactive. In this case, you must have or create a Firebase account, and authenticate using that account. The command prompts you to select a Firebase project for deployment -After the command produces an optimal build of your application (equivalent to `ng deploy --prod`), it'll upload the production assets to Firebase. +The command builds your application and uploads the production assets to Firebase. In the table below, you can find a list of packages which implement deployment functionality to different platforms. The `deploy` command for each package may require different command line options. You can read more by following the links associated with the package names below: @@ -92,7 +92,7 @@ For the simplest deployment, create a production build and copy the output direc - ng build --prod + ng build @@ -135,7 +135,7 @@ To deploy your Angular application to [GitHub Pages](https://help.github.com/art - ng build --prod --output-path docs --base-href /your_project_name/ + ng build --output-path docs --base-href /your_project_name/ @@ -299,7 +299,7 @@ Read about how to enable CORS for specific servers at {@a optimize} ## Production optimizations -The `--prod` _meta-flag_ engages the following build optimization features. +The `production` configuration engages the following build optimization features. * [Ahead-of-Time (AOT) Compilation](guide/aot-compiler): pre-compiles Angular component templates. * [Production mode](#enable-prod-mode): deploys the production environment which enables _production mode_. @@ -323,9 +323,10 @@ In addition to build optimizations, Angular also has a runtime production mode. -Switching to _production mode_ makes it run faster by disabling development specific checks such as the dual change detection cycles. - -When you enable production builds via `--prod` command line flag, the runtime production mode is enabled as well. +_Production mode_ improves application performance by disabling development-only safety +checks and debugging utilities, such as the expression-changed-after-checked detection. +Building your application with the production configuration automatically enables Angular's +runtime production mode. {@a lazy-loading} @@ -394,7 +395,7 @@ Build your app for production _including the source maps_ - ng build --prod --source-map + ng build --source-map diff --git a/aio/content/guide/glossary.md b/aio/content/guide/glossary.md index b154873562..28f797e66d 100644 --- a/aio/content/guide/glossary.md +++ b/aio/content/guide/glossary.md @@ -907,7 +907,7 @@ A buildable or runnable subset of a [project](#project), configured as an object In the `angular.json` file, each project has an "architect" section that contains targets which configure builders. Some of these targets correspond to [CLI commands](#cli), such as `build`, `serve`, `test`, and `lint`. -For example, the Architect builder invoked by the `ng build` command to compile a project uses a particular build tool, and has a default configuration whose values can be overridden on the command line. The `build` target also defines an alternate configuration for a "production" build, that can be invoked with the `--prod` flag on the `build` command. +For example, the Architect builder invoked by the `ng build` command to compile a project uses a particular build tool, and has a default configuration with values that you can override on the command line. The `build` target also defines an alternate configuration for a "development" build, which you can invoke with the `--configuration development` flag on the `build` command. The Architect tool provides a set of builders. The [`ng new` command](cli/new) provides a set of targets for the initial application project. The [`ng generate application`](cli/generate#application) and [`ng generate library`](cli/generate#library) commands provide a set of targets for each new [project](#project). These targets, their options and configurations, can be customized to meet the needs of your project. For example, you may want to add a "staging" or "testing" configuration to a project's "build" target. diff --git a/aio/content/guide/i18n.md b/aio/content/guide/i18n.md index bef75a1d6d..63c1f4804b 100644 --- a/aio/content/guide/i18n.md +++ b/aio/content/guide/i18n.md @@ -642,7 +642,7 @@ You can also use the `--localize` option with the [`ng build`](/cli/build "CLI r The CLI builds all locales defined in the build configuration, which is similar to setting the `"localize"` option to `true` as described in the previous section. - ng build --prod --localize + ng build --localize {@a localize-build-one-locale} diff --git a/aio/content/guide/service-worker-config.md b/aio/content/guide/service-worker-config.md index 6135f2f218..140fb46908 100644 --- a/aio/content/guide/service-worker-config.md +++ b/aio/content/guide/service-worker-config.md @@ -9,7 +9,7 @@ A basic understanding of the following: The `ngsw-config.json` configuration file specifies which files and data URLs the Angular service worker should cache and how it should update the cached files and data. The [Angular CLI](cli) -processes the configuration file during `ng build --prod`. Manually, you can process it with the +processes the configuration file during `ng build`. Manually, you can process it with the `ngsw-config` tool (where `` is the name of the project being built): diff --git a/aio/content/guide/service-worker-getting-started.md b/aio/content/guide/service-worker-getting-started.md index 7c51c21ce1..dde674bb8a 100644 --- a/aio/content/guide/service-worker-getting-started.md +++ b/aio/content/guide/service-worker-getting-started.md @@ -32,7 +32,7 @@ The above command completes the following actions: Now, build the project: ```sh -ng build --prod +ng build ``` The CLI project is now set up to use the Angular service worker. @@ -130,7 +130,7 @@ next step is understanding how updates work. Let's make a change to the applicat 6. Build and run the server again: ```sh -ng build --prod +ng build http-server -p 8080 -c-1 dist/ ``` diff --git a/aio/content/guide/workspace-config.md b/aio/content/guide/workspace-config.md index 1250562643..95865c3cec 100644 --- a/aio/content/guide/workspace-config.md +++ b/aio/content/guide/workspace-config.md @@ -174,7 +174,11 @@ The `architect/build` section configures defaults for options of the `ng build` ### Alternate build configurations -By default, a `production` configuration is defined, and the `ng build` command has `--prod` option that builds using this configuration. The `production` configuration sets defaults that optimize the app in a number of ways, such as bundling files, minimizing excess whitespace, removing comments and dead code, and rewriting code to use short, cryptic names ("minification"). +Angular CLI comes with two build configurations: `production` and `development`. By default, the `ng build` command uses the `production` configuration, which applies a number of build optimizations, including: +* Bundling files +* Minimizing excess whitespace +* Removing comments and dead code +* Rewriting code to use short, mangled names (minification) You can define and name additional alternate configurations (such as `stage`, for instance) appropriate to your development process. Some examples of different build configurations are `stable`, `archive` and `next` used by AIO itself, and the individual locale-specific configurations required for building localized versions of an app. For details, see [Internationalization (i18n)](guide/i18n#merge-aot). @@ -182,8 +186,6 @@ You can select an alternate configuration by passing its name to the `--configur You can also pass in more than one configuration name as a comma-separated list. For example, to apply both `stage` and `fr` build configurations, use the command `ng build --configuration stage,fr`. In this case, the command parses the named configurations from left to right. If multiple configurations change the same setting, the last-set value is the final one. -If the `--prod` command line flag is also used, it is applied first, and its settings can be overridden by any configurations specified via the `--configuration` flag. - {@a build-props} ### Additional build and test options diff --git a/aio/content/start/start-deployment.md b/aio/content/start/start-deployment.md index 20d84a9378..d99ae2fb7a 100644 --- a/aio/content/start/start-deployment.md +++ b/aio/content/start/start-deployment.md @@ -51,10 +51,10 @@ A best practice is to run your project locally before you deploy it. To run your {@a building} ## Building and hosting your application - 1. To build your application for production, use the `build` command with the `prod` flag. + 1. To build your application for production, use the `build` command. By default, this command uses the `production` build configuration. ```sh - ng build --prod + ng build ``` This command creates a `dist` folder in the application root directory with all the files that a hosting service needs for serving your application.