5 lines
24 KiB
JSON
5 lines
24 KiB
JSON
{
|
|
"id": "guide/build",
|
|
"title": "Building and serving Angular apps",
|
|
"contents": "\n\n\n<div class=\"github-links\">\n <a href=\"https://github.com/angular/angular/edit/master/aio/content/guide/build.md?message=docs%3A%20describe%20your%20change...\" aria-label=\"Suggest Edits\" title=\"Suggest Edits\"><i class=\"material-icons\" aria-hidden=\"true\" role=\"img\">mode_edit</i></a>\n</div>\n\n\n<div class=\"content\">\n <h1 id=\"building-and-serving-angular-apps\">Building and serving Angular apps<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#building-and-serving-angular-apps\"><i class=\"material-icons\">link</i></a></h1>\n<p>This page discusses build-specific configuration options for Angular projects.</p>\n<a id=\"app-environments\"></a>\n<h2 id=\"configuring-application-environments\">Configuring application environments<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#configuring-application-environments\"><i class=\"material-icons\">link</i></a></h2>\n<p>You can define different named build configurations for your project, such as <em>stage</em> and <em>production</em>, with different defaults.</p>\n<p>Each named configuration can have defaults for any of the options that apply to the various <a href=\"guide/glossary#target\">builder targets</a>, such as <code>build</code>, <code>serve</code>, and <code>test</code>. The <a href=\"cli\">Angular CLI</a> <code>build</code>, <code>serve</code>, and <code>test</code> commands can then replace files with appropriate versions for your intended target environment.</p>\n<h3 id=\"configure-environment-specific-defaults\">Configure environment-specific defaults<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#configure-environment-specific-defaults\"><i class=\"material-icons\">link</i></a></h3>\n<p>A project's <code>src/environments/</code> folder contains the base configuration file, <code>environment.ts</code>, which provides a default environment.\nYou can add override defaults for additional environments, such as production and staging, in target-specific configuration files.</p>\n<p>For example:</p>\n<code-example>\n└──myProject/src/environments/\n └──environment.ts\n └──environment.prod.ts\n └──environment.stage.ts\n</code-example>\n<p>The base file <code>environment.ts</code>, contains the default environment settings. For example:</p>\n<code-example>\nexport const environment = {\n production: false\n};\n</code-example>\n<p>The <code>build</code> command uses this as the build target when no environment is specified.\nYou can add further variables, either as additional properties on the environment object, or as separate objects.\nFor example, the following adds a default for a variable to the default environment:</p>\n<code-example>\nexport const environment = {\n production: false,\n apiUrl: 'http://my-api-url'\n};\n</code-example>\n<p>You can add target-specific configuration files, such as <code>environment.prod.ts</code>.\nThe following sets content sets default values for the production build target:</p>\n<code-example>\nexport const environment = {\n production: true,\n apiUrl: 'http://my-prod-url'\n};\n</code-example>\n<h3 id=\"using-environment-specific-variables-in-your-app\">Using environment-specific variables in your app<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#using-environment-specific-variables-in-your-app\"><i class=\"material-icons\">link</i></a></h3>\n<p>The following application structure configures build targets for production and staging environments:</p>\n<code-example>\n└── src\n └── app\n ├── app.component.html\n └── app.component.ts\n └── environments\n ├── environment.prod.ts\n ├── environment.staging.ts\n └── environment.ts\n</code-example>\n<p>To use the environment configurations you have defined, your components must import the original environments file:</p>\n<code-example>\nimport { environment } from './../environments/environment';\n</code-example>\n<p>This ensures that the build and serve commands can find the configurations for specific build targets.</p>\n<p>The following code in the component file (<code>app.component.ts</code>) uses an environment variable defined in the configuration files.</p>\n<code-example>\nimport { <a href=\"api/core/Component\" class=\"code-anchor\">Component</a> } from '@angular/core';\nimport { environment } from './../environments/environment';\n\n@<a href=\"api/core/Component\" class=\"code-anchor\">Component</a>({\n selector: 'app-root',\n templateUrl: './app.component.html',\n styleUrls: ['./app.component.css']\n})\nexport class AppComponent {\n constructor() {\n console.log(environment.production); // Logs false for default environment\n }\n title = 'app works!';\n}\n</code-example>\n<a id=\"file-replacement\"></a>\n<h2 id=\"configure-target-specific-file-replacements\">Configure target-specific file replacements<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#configure-target-specific-file-replacements\"><i class=\"material-icons\">link</i></a></h2>\n<p>The main CLI configuration file, <code>angular.json</code>, contains a <code>fileReplacements</code> section in the configuration for each build target, which allows you to replace any file in the TypeScript program with a target-specific version of that file.\nThis is useful for including target-specific code or variables in a build that targets a specific environment, such as production or staging.</p>\n<p>By default no files are replaced.\nYou can add file replacements for specific build targets.\nFor example:</p>\n<code-example>\n\"configurations\": {\n \"production\": {\n \"fileReplacements\": [\n {\n \"replace\": \"src/environments/environment.ts\",\n \"with\": \"src/environments/environment.prod.ts\"\n }\n ],\n ...\n</code-example>\n<p>This means that when you build your production configuration with <code>ng build --configuration production</code>, the <code>src/environments/environment.ts</code> file is replaced with the target-specific version of the file, <code>src/environments/environment.prod.ts</code>.</p>\n<p>You can add additional configurations as required. To add a staging environment, create a copy of <code>src/environments/environment.ts</code> called <code>src/environments/environment.staging.ts</code>, then add a <code>staging</code> configuration to <code>angular.json</code>:</p>\n<code-example>\n\"configurations\": {\n \"production\": { ... },\n \"staging\": {\n \"fileReplacements\": [\n {\n \"replace\": \"src/environments/environment.ts\",\n \"with\": \"src/environments/environment.staging.ts\"\n }\n ]\n }\n}\n</code-example>\n<p>You can add more configuration options to this target environment as well.\nAny option that your build supports can be overridden in a build target configuration.</p>\n<p>To build using the staging configuration, run the following command:</p>\n<code-example language=\"sh\" class=\"code-shell\">\n ng build --configuration=staging\n</code-example>\n<p>You can also configure the <code>serve</code> command to use the targeted build configuration if you add it to the \"serve:configurations\" section of <code>angular.json</code>:</p>\n<code-example>\n\"serve\": {\n \"builder\": \"@angular-devkit/build-angular:dev-server\",\n \"options\": {\n \"browserTarget\": \"your-project-name:build\"\n },\n \"configurations\": {\n \"production\": {\n \"browserTarget\": \"your-project-name:build:production\"\n },\n \"staging\": {\n \"browserTarget\": \"your-project-name:build:staging\"\n }\n }\n},\n</code-example>\n<a id=\"size-budgets\"></a>\n<a id=\"configure-size-budgets\"></a>\n<h2 id=\"configuring-size-budgets\">Configuring size budgets<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#configuring-size-budgets\"><i class=\"material-icons\">link</i></a></h2>\n<p>As applications grow in functionality, they also grow in size.\nThe CLI allows you to set size thresholds in your configuration to ensure that parts of your application stay within size boundaries that you define.</p>\n<p>Define your size boundaries in the CLI configuration file, <code>angular.json</code>, in a <code>budgets</code> section for each <a href=\"guide/build#app-environments\">configured environment</a>.</p>\n<code-example>\n{\n ...\n \"configurations\": {\n \"production\": {\n ...\n budgets: []\n }\n }\n}\n</code-example>\n<p>You can specify size budgets for the entire app, and for particular parts.\nEach budget entry configures a budget of a given type.\nSpecify size values in the following formats:</p>\n<ul>\n<li>\n<p>123 or 123b: Size in bytes</p>\n</li>\n<li>\n<p>123kb: Size in kilobytes</p>\n</li>\n<li>\n<p>123mb: Size in megabytes</p>\n</li>\n<li>\n<p>12%: Percentage of size relative to baseline. (Not valid for baseline values.)</p>\n</li>\n</ul>\n<p>When you configure a budget, the build system warns or reports an error when a given part of the app reaches or exceeds a boundary size that you set.</p>\n<p>Each budget entry is a JSON object with the following properties:</p>\n<table>\n <tbody><tr>\n <th>Property</th>\n <th>Value</th>\n </tr>\n <tr>\n <td>type</td>\n <td>\n<p> The type of budget. One of:</p>\n<ul>\n<li>\n<p><code>bundle</code> - The size of a specific bundle.</p>\n</li>\n<li>\n<p><code>initial</code> - The initial size of the app.</p>\n</li>\n<li>\n<p><code>allScript</code> - The size of all scripts.</p>\n</li>\n<li>\n<p><code>all</code> - The size of the entire app.</p>\n</li>\n<li>\n<p><code>anyComponentStyle</code> - This size of any one component stylesheet.</p>\n</li>\n<li>\n<p><code>anyScript</code> - The size of any one script.</p>\n</li>\n<li>\n<p><code>any</code> - The size of any file.</p>\n </li></ul></td>\n </tr>\n <tr>\n <td>name</td>\n <td>\n<p> The name of the bundle (for <code>type=bundle</code>).</p>\n </td>\n </tr>\n <tr>\n <td>baseline</td>\n <td>The baseline size for comparison.</td>\n </tr>\n <tr>\n <td>maximumWarning</td>\n <td>The maximum threshold for warning relative to the baseline.</td>\n </tr>\n <tr>\n <td>maximumError</td>\n <td>The maximum threshold for error relative to the baseline.</td>\n </tr>\n <tr>\n <td>minimumWarning</td>\n <td>The minimum threshold for warning relative to the baseline.</td>\n </tr>\n <tr>\n <td>minimumError</td>\n <td>The minimum threshold for error relative to the baseline.</td>\n </tr>\n <tr>\n <td>warning</td>\n <td>The threshold for warning relative to the baseline (min & max).</td>\n </tr>\n <tr>\n <td>error</td>\n <td>The threshold for error relative to the baseline (min & max).</td>\n </tr>\n</tbody></table>\n\n\n<a id=\"commonjs\"></a>\n<h2 id=\"configuring-commonjs-dependencies\">Configuring CommonJS dependencies<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#configuring-commonjs-dependencies\"><i class=\"material-icons\">link</i></a></h2>\n<div class=\"alert is-important\">\n<p>It is recommended that you avoid depending on CommonJS modules in your Angular applications.\nDepending on CommonJS modules can prevent bundlers and minifiers from optimizing your application, which results in larger bundle sizes.\nInstead, it is recommended that you use <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import\">ECMAScript modules</a> in your entire application.\nFor more information, see <a href=\"https://web.dev/commonjs-larger-bundles/\">How CommonJS is making your bundles larger</a>.</p>\n</div>\n<p>The Angular CLI outputs warnings if it detects that your browser application depends on CommonJS modules.\nTo disable these warnings, you can add the CommonJS module name to <code>allowedCommonJsDependencies</code> option in the <code>build</code> options located in <code>angular.json</code> file.</p>\n<code-example lang=\"json\">\n\"build\": {\n \"builder\": \"@angular-devkit/build-angular:<a href=\"api/animations/browser\" class=\"code-anchor\">browser</a>\",\n \"options\": {\n \"allowedCommonJsDependencies\": [\n \"lodash\"\n ]\n ...\n }\n ...\n},\n</code-example>\n<a id=\"browser-compat\"></a>\n<h2 id=\"configuring-browser-compatibility\">Configuring browser compatibility<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#configuring-browser-compatibility\"><i class=\"material-icons\">link</i></a></h2>\n<p>The CLI uses <a href=\"https://github.com/postcss/autoprefixer\">Autoprefixer</a> to ensure compatibility with different browser and browser versions.\nYou may find it necessary to target specific browsers or exclude certain browser versions from your build.</p>\n<p>Internally, Autoprefixer relies on a library called <a href=\"https://github.com/browserslist/browserslist\">Browserslist</a> to figure out which browsers to support with prefixing.\nBrowserlist looks for configuration options in a <code>browserslist</code> property of the package configuration file, or in a configuration file named <code>.browserslistrc</code>.\nAutoprefixer looks for the <code>browserslist</code> configuration when it prefixes your CSS.</p>\n<ul>\n<li>You can tell Autoprefixer what browsers to target by adding a browserslist property to the package configuration file, <code>package.json</code>:</li>\n</ul>\n<code-example>\n \"browserslist\": [\n \"> 1%\",\n \"last 2 versions\"\n ]\n</code-example>\n<ul>\n<li>Alternatively, you can add a new file, <code>.browserslistrc</code>, to the project directory, that specifies browsers you want to support:</li>\n</ul>\n<code-example>\n ### Supported Browsers\n > 1%\n last 2 versions\n</code-example>\n<p>See the <a href=\"https://github.com/browserslist/browserslist\">browserslist repo</a> for more examples of how to target specific browsers and versions.</p>\n<h3 id=\"backward-compatibility-with-lighthouse\">Backward compatibility with Lighthouse<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#backward-compatibility-with-lighthouse\"><i class=\"material-icons\">link</i></a></h3>\n<p>If you want to produce a progressive web app and are using <a href=\"https://developers.google.com/web/tools/lighthouse/\">Lighthouse</a> to grade the project, add the following <code>browserslist</code> entry to your <code>package.json</code> file, in order to eliminate the <a href=\"https://developers.google.com/web/tools/lighthouse/audits/old-flexbox\">old flexbox</a> prefixes:</p>\n<code-example>\n\"browserslist\": [\n \"last 2 versions\",\n \"not ie <= 10\",\n \"not ie_mob <= 10\"\n]\n</code-example>\n<h3 id=\"backward-compatibility-with-css-grid\">Backward compatibility with CSS grid<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#backward-compatibility-with-css-grid\"><i class=\"material-icons\">link</i></a></h3>\n<p>CSS grid layout support in Autoprefixer, which was previously on by default, is off by default in Angular 8 and higher.</p>\n<p>To use CSS grid with IE10/11, you must explicitly enable it using the <code>autoplace</code> option.\nTo do this, add the following to the top of the global styles file (or within a specific css selector scope):</p>\n<code-example>\n/* autoprefixer grid: autoplace */\n</code-example>\n<p>or</p>\n<code-example>\n/* autoprefixer grid: no-autoplace */\n</code-example>\n<p>For more information, see <a href=\"https://autoprefixer.github.io/\">Autoprefixer documentation</a>.</p>\n<a id=\"proxy\"></a>\n<h2 id=\"proxying-to-a-backend-server\">Proxying to a backend server<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#proxying-to-a-backend-server\"><i class=\"material-icons\">link</i></a></h2>\n<p>You can use the <a href=\"https://webpack.js.org/configuration/dev-server/#devserverproxy\">proxying support</a> in the <code>webpack</code> dev server to divert certain URLs to a backend server, by passing a file to the <code>--proxy-config</code> build option.\nFor example, to divert all calls for <code>http://localhost:4200/api</code> to a server running on <code>http://localhost:3000/api</code>, take the following steps.</p>\n<ol>\n<li>\n<p>Create a file <code>proxy.conf.json</code> in your project's <code>src/</code> folder.</p>\n</li>\n<li>\n<p>Add the following content to the new proxy file:</p>\n<code-example>\n{\n \"/api\": {\n \"target\": \"http://localhost:3000\",\n \"secure\": false\n }\n}\n</code-example>\n</li>\n<li>\n<p>In the CLI configuration file, <code>angular.json</code>, add the <code>proxyConfig</code> option to the <code>serve</code> target:</p>\n<code-example>\n...\n\"architect\": {\n \"serve\": {\n \"builder\": \"@angular-devkit/build-angular:dev-server\",\n \"options\": {\n \"browserTarget\": \"your-application-name:build\",\n \"proxyConfig\": \"src/proxy.conf.json\"\n },\n...\n</code-example>\n</li>\n<li>\n<p>To run the dev server with this proxy configuration, call <code>ng serve</code>.</p>\n</li>\n</ol>\n<p>You can edit the proxy configuration file to add configuration options; some examples are given below.\nFor a description of all options, see <a href=\"https://webpack.js.org/configuration/dev-server/#devserverproxy\">webpack DevServer documentation</a>.</p>\n<p>Note that if you edit the proxy configuration file, you must relaunch the <code>ng serve</code> process to make your changes effective.</p>\n<h3 id=\"rewrite-the-url-path\">Rewrite the URL path<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#rewrite-the-url-path\"><i class=\"material-icons\">link</i></a></h3>\n<p>The <code>pathRewrite</code> proxy configuration option lets you rewrite the URL path at run time.\nFor example, you can specify the following <code>pathRewrite</code> value to the proxy configuration to remove \"api\" from the end of a path.</p>\n<code-example>\n{\n \"/api\": {\n \"target\": \"http://localhost:3000\",\n \"secure\": false,\n \"pathRewrite\": {\n \"^/api\": \"\"\n }\n }\n}\n</code-example>\n<p>If you need to access a backend that is not on <code>localhost</code>, set the <code>changeOrigin</code> option as well. For example:</p>\n<code-example>\n{\n \"/api\": {\n \"target\": \"http://npmjs.org\",\n \"secure\": false,\n \"pathRewrite\": {\n \"^/api\": \"\"\n },\n \"changeOrigin\": true\n }\n}\n</code-example>\n<p>To help determine whether your proxy is working as intended, set the <code>logLevel</code> option. For example:</p>\n<code-example>\n{\n \"/api\": {\n \"target\": \"http://localhost:3000\",\n \"secure\": false,\n \"pathRewrite\": {\n \"^/api\": \"\"\n },\n \"logLevel\": \"debug\"\n }\n}\n</code-example>\n<p>Proxy log levels are <code>info</code> (the default), <code>debug</code>, <code>warn</code>, <code>error</code>, and <code>silent</code>.</p>\n<h3 id=\"proxy-multiple-entries\">Proxy multiple entries<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#proxy-multiple-entries\"><i class=\"material-icons\">link</i></a></h3>\n<p>You can proxy multiple entries to the same target by defining the configuration in JavaScript.</p>\n<p>Set the proxy configuration file to <code>proxy.conf.js</code> (instead of <code>proxy.conf.json</code>), and specify configuration files as in the following example.</p>\n<code-example>\nconst PROXY_CONFIG = [\n {\n context: [\n \"/my\",\n \"/many\",\n \"/endpoints\",\n \"/i\",\n \"/need\",\n \"/to\",\n \"/proxy\"\n ],\n target: \"http://localhost:3000\",\n secure: false\n }\n]\n\nmodule.exports = PROXY_CONFIG;\n</code-example>\n<p>In the CLI configuration file, <code>angular.json</code>, point to the JavaScript proxy configuration file:</p>\n<code-example>\n...\n\"architect\": {\n \"serve\": {\n \"builder\": \"@angular-devkit/build-angular:dev-server\",\n \"options\": {\n \"browserTarget\": \"your-application-name:build\",\n \"proxyConfig\": \"src/proxy.conf.js\"\n },\n...\n</code-example>\n<h3 id=\"bypass-the-proxy\">Bypass the proxy<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#bypass-the-proxy\"><i class=\"material-icons\">link</i></a></h3>\n<p>If you need to optionally bypass the proxy, or dynamically change the request before it's sent, add the bypass option, as shown in this JavaScript example.</p>\n<code-example>\nconst PROXY_CONFIG = {\n \"/api/proxy\": {\n \"target\": \"http://localhost:3000\",\n \"secure\": false,\n \"bypass\": function (req, res, proxyOptions) {\n if (req.headers.accept.indexOf(\"html\") !== -1) {\n console.log(\"Skipping proxy for <a href=\"api/animations/browser\" class=\"code-anchor\">browser</a> request.\");\n return \"/index.html\";\n }\n req.headers[\"X-Custom-Header\"] = \"yes\";\n }\n }\n}\n\nmodule.exports = PROXY_CONFIG;\n</code-example>\n<h3 id=\"using-corporate-proxy\">Using corporate proxy<a title=\"Link to this heading\" class=\"header-link\" aria-hidden=\"true\" href=\"guide/build#using-corporate-proxy\"><i class=\"material-icons\">link</i></a></h3>\n<p>If you work behind a corporate proxy, the backend cannot directly proxy calls to any URL outside your local network.\nIn this case, you can configure the backend proxy to redirect calls through your corporate proxy using an agent:</p>\n<code-example language=\"none\" class=\"code-shell\">\nnpm install --save-dev https-proxy-agent\n</code-example>\n<p>When you define an environment variable <code>http_proxy</code> or <code>HTTP_PROXY</code>, an agent is automatically added to pass calls through your corporate proxy when running <code>npm start</code>.</p>\n<p>Use the following content in the JavaScript configuration file.</p>\n<code-example>\nvar HttpsProxyAgent = require('https-proxy-agent');\nvar proxyConfig = [{\n context: '/api',\n target: 'http://your-remote-server.com:3000',\n secure: false\n}];\n\nfunction setupForCorporateProxy(proxyConfig) {\n var proxyServer = process.env.http_proxy || process.env.HTTP_PROXY;\n if (proxyServer) {\n var agent = new HttpsProxyAgent(proxyServer);\n console.log('Using corporate proxy server: ' + proxyServer);\n proxyConfig.forEach(function(entry) {\n entry.agent = agent;\n });\n }\n return proxyConfig;\n}\n\nmodule.exports = setupForCorporateProxy(proxyConfig);\n</code-example>\n\n \n</div>\n\n<!-- links to this doc:\n - guide/aot-compiler\n - guide/architecture-next-steps\n - guide/i18n\n - guide/npm-packages\n - guide/strict-mode\n - guide/upgrade-setup\n - guide/workspace-config\n - start/start-deployment\n-->\n<!-- links from this doc:\n - api/animations/browser\n - api/core/Component\n - cli\n - guide/build#app-environments\n - guide/build#backward-compatibility-with-css-grid\n - guide/build#backward-compatibility-with-lighthouse\n - guide/build#building-and-serving-angular-apps\n - guide/build#bypass-the-proxy\n - guide/build#configure-environment-specific-defaults\n - guide/build#configure-target-specific-file-replacements\n - guide/build#configuring-application-environments\n - guide/build#configuring-browser-compatibility\n - guide/build#configuring-commonjs-dependencies\n - guide/build#configuring-size-budgets\n - guide/build#proxy-multiple-entries\n - guide/build#proxying-to-a-backend-server\n - guide/build#rewrite-the-url-path\n - guide/build#using-corporate-proxy\n - guide/build#using-environment-specific-variables-in-your-app\n - guide/glossary#target\n - https://autoprefixer.github.io/\n - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import\n - https://developers.google.com/web/tools/lighthouse/\n - https://developers.google.com/web/tools/lighthouse/audits/old-flexbox\n - https://github.com/angular/angular/edit/master/aio/content/guide/build.md?message=docs%3A%20describe%20your%20change...\n - https://github.com/browserslist/browserslist\n - https://github.com/postcss/autoprefixer\n - https://web.dev/commonjs-larger-bundles/\n - https://webpack.js.org/configuration/dev-server/#devserverproxy\n-->"
|
|
} |