From d574b14934736886d73277006e7b918625db413e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Shevitz=20=F0=9F=94=B5?= <dshevitz@google.com>
Date: Thu, 28 May 2020 17:36:55 +0000
Subject: [PATCH] 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
---
 aio/content/guide/build.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/aio/content/guide/build.md b/aio/content/guide/build.md
index f9e607d616..91c8e2c8e8 100644
--- a/aio/content/guide/build.md
+++ b/aio/content/guide/build.md
@@ -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}