docs: describe how to configure CommonJS modules (#37331)

In version 10, we have a new option for the `angular.json` file,
`allowedCommonJsDependencies`, so users can opt in to support
CommonJS modules.

PR Close #37331
This commit is contained in:
David Shevitz 🔵 2020-05-28 17:36:55 +00:00 committed by Misko Hevery
parent d330cd85ac
commit adc9d5cdcb
1 changed files with 27 additions and 0 deletions

View File

@ -262,6 +262,33 @@ Each budget entry is a JSON object with the following properties:
</table>
{@a commonjs }
## Configuring CommonJS dependencies
<div class="alert is-important">
It is recommended that you avoid depending on CommonJS modules in your Angular applications.
Depending on CommonJS modules can prevent bundlers and minifiers from optimizing your application, which results in larger bundle sizes.
Instead, it is recommended that you use [ECMAScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) in your entire application.
For more information, see [How CommonJS is making your bundles larger](https://web.dev/commonjs-larger-bundles/).
</div>
The Angular CLI outputs warnings if it detects that your browser application depends on CommonJS modules.
To disable these warnings, you can add the CommonJS module name to `allowedCommonJsDependencies` option in the `build` options located in `angular.json` file.
<code-example lang="json">
"build": {
"builder": "@angular-devkit/build-angular:browser",
"options": {
"allowedCommonJsDependencies": [
"lodash"
]
...
}
...
},
</code-example>
{@a browser-compat}