feat(webpack): migrate to webpack.config file (#14607)

docs/generated/manifests/menus.json

@@ -6251,6 +6251,31 @@
         "path": "/packages/webpack",
         "name": "webpack",
         "children": [
+          {
+            "id": "documents",
+            "path": "/packages/webpack/documents",
+            "name": "documents",
+            "children": [
+              {
+                "name": "Configure webpack on your Nx workspace",
+                "path": "/packages/webpack/documents/webpack-config-setup",
+                "id": "webpack-config-setup",
+                "isExternal": false,
+                "children": [],
+                "disableCollapsible": false
+              },
+              {
+                "name": "Webpack plugins",
+                "path": "/packages/webpack/documents/webpack-plugins",
+                "id": "webpack-plugins",
+                "isExternal": false,
+                "children": [],
+                "disableCollapsible": false
+              }
+            ],
+            "isExternal": false,
+            "disableCollapsible": false
+          },
           {
             "id": "executors",
             "path": "/packages/webpack/executors",

docs/generated/manifests/packages.json

@@ -2813,7 +2813,30 @@
     "name": "webpack",
     "packageName": "@nrwl/webpack",
     "description": "The Nx Plugin for Webpack contains executors and generators that support building applications using Webpack.",
-    "documents": {},
+    "documents": {
+      "/packages/webpack/documents/webpack-config-setup": {
+        "id": "webpack-config-setup",
+        "name": "Configure webpack on your Nx workspace",
+        "description": "Configure webpack on your Nx workspace",
+        "file": "generated/packages/webpack/documents/webpack-config-setup",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/packages/webpack/documents/webpack-config-setup",
+        "tags": [],
+        "originalFilePath": "shared/packages/webpack/webpack-config-setup"
+      },
+      "/packages/webpack/documents/webpack-plugins": {
+        "id": "webpack-plugins",
+        "name": "Webpack plugins",
+        "description": "Webpack plugins",
+        "file": "generated/packages/webpack/documents/webpack-plugins",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/packages/webpack/documents/webpack-plugins",
+        "tags": [],
+        "originalFilePath": "shared/packages/webpack/webpack-plugins"
+      }
+    },
     "root": "/packages/webpack",
     "source": "/packages/webpack/src",
     "executors": {

docs/generated/packages-metadata.json

@@ -2782,7 +2782,30 @@
   },
   {
     "description": "The Nx Plugin for Webpack contains executors and generators that support building applications using Webpack.",
-    "documents": [],
+    "documents": [
+      {
+        "id": "webpack-config-setup",
+        "name": "Configure webpack on your Nx workspace",
+        "description": "Configure webpack on your Nx workspace",
+        "file": "generated/packages/webpack/documents/webpack-config-setup",
+        "itemList": [],
+        "isExternal": false,
+        "path": "webpack/documents/webpack-config-setup",
+        "tags": [],
+        "originalFilePath": "shared/packages/webpack/webpack-config-setup"
+      },
+      {
+        "id": "webpack-plugins",
+        "name": "Webpack plugins",
+        "description": "Webpack plugins",
+        "file": "generated/packages/webpack/documents/webpack-plugins",
+        "itemList": [],
+        "isExternal": false,
+        "path": "webpack/documents/webpack-plugins",
+        "tags": [],
+        "originalFilePath": "shared/packages/webpack/webpack-plugins"
+      }
+    ],
     "executors": [
       {
         "description": "Run webpack build.",

docs/generated/packages/webpack/documents/webpack-config-setup.md

@@ -0,0 +1,108 @@
+# Configure webpack on your Nx workspace
+
+You can configure Webpack using a `webpack.config.js` file in your project. You can set the path to this file in your `project.json` file, in the `build` target options:
+
+```json
+//...
+"my-app": {
+    "targets": {
+        //...
+        "build": {
+            "executor": "@nrwl/webpack:webpack",
+            //...
+            "options": {
+                //...
+                "webpackConfig": "apps/my-app/webpack.config.js"
+            },
+            "configurations": {
+                ...
+            }
+        },
+    }
+}
+```
+
+In that file, you can add the necessary configuration for Webpack. You can read more on how to configure webpack in the [Webpack documentation](https://webpack.js.org/concepts/configuration/).
+
+## Using webpack with `isolatedConfig`
+
+Setting `isolatedConfig` to `true` in your `project.json` file means that Nx will not apply the Nx webpack plugins automatically. In that case, the Nx plugins need to be applied in the project's `webpack.config.js` file (e.g. `withNx`, `withReact`, etc.). So don't forget to also specify the path to your webpack config file (using the `webpackConfig` option).
+
+Note that this is the new default setup for webpack in the latest version of Nx.
+
+Set `isolatedConfig` to `true` in your `project.json` file in the `build` target options like this:
+
+```json
+//...
+"my-app": {
+    "targets": {
+        //...
+        "build": {
+            "executor": "@nrwl/webpack:webpack",
+            //...
+            "options": {
+                //...
+                "webpackConfig": "apps/my-app/webpack.config.js",
+                "isolatedConfig": true
+            },
+            "configurations": {
+                ...
+            }
+        },
+    }
+}
+```
+
+Now, you need to manually add the Nx webpack plugins in your `webpack.config.js` file for Nx to work properly. Let's see how to do that.
+
+### Basic configuration for Nx
+
+You should start with a basic webpack configuration for Nx in your project, that looks like this:
+
+```ts
+// apps/my-app/webpack.config.js
+const { composePlugins, withNx } = require('@nrwl/webpack');
+
+module.exports = composePlugins(withNx(), (config, { options, context }) => {
+  // customize webpack config here
+  return config;
+});
+```
+
+The `withNx()` plugin adds the necessary configuration for Nx to work with Webpack. The `composePlugins` function allows you to add other plugins to the configuration.
+
+#### The `composePlugins` function
+
+The `composePlugins` function takes a list of plugins and a function, and returns a webpack `Configuration` object. The `composePlugins` function is an enhanced version of the [webpack configuration function](https://webpack.js.org/configuration/configuration-types/#exporting-a-function), which allows you to add plugins to the configuration, and provides you with a function which accepts two arguments:
+
+1. `config`: The webpack configuration object.
+2. An object with the following properties:
+   - `options`: The options passed to the `@nrwl/webpack:webpack` executor.
+   - `context`: The context passed of the `@nrwl/webpack:webpack` executor.
+
+This gives you the ability to customize the webpack configuration as needed, and make use of the options and context passed to the executor, as well.
+
+### Add configurations for other functionalities
+
+In addition to the basic configuration, you can add configurations for other frameworks or features. The `@nrwl/webpack` package provides plugins such as `withWeb` and `withReact`. This plugins provide features such as TS support, CSS support, JSX support, etc. You can read more about how these plugins work and how to use them in our [Webpack Plugins guide](/packages/webpack/documents/webpack-plugins).
+
+You may still reconfigure everything manually, without using the Nx plugins. However, these plugins ensure that you have the necessary configuration for Nx to work with your project.
+
+Here is an example of a configuration that uses the `withReact` plugin:
+
+```ts
+// apps/my-react-app/webpack.config.js
+const { composePlugins, withNx } = require('@nrwl/webpack');
+const { withReact } = require('@nrwl/react');
+
+// Nx plugins for webpack.
+module.exports = composePlugins(
+  withNx(),
+  withReact(),
+  (config, { options, context }) => {
+    // Update the webpack config as needed here.
+    // e.g. config.plugins.push(new MyPlugin())
+    return config;
+  }
+);
+```

docs/generated/packages/webpack/documents/webpack-plugins.md

@@ -0,0 +1,9 @@
+# Webpack plugins
+
+Coming soon.
+
+## `withNx`
+
+## `withWeb`
+
+## `withReact`

docs/generated/packages/webpack/executors/webpack.json

@@ -463,6 +463,7 @@
         ]
       }
     },
+    "examplesFile": "`project.json`:\n\n```json\n//...\n\"my-app\": {\n    \"targets\": {\n        //...\n        \"build\": {\n            \"executor\": \"@nrwl/webpack:webpack\",\n            //...\n            //...\n            \"options\": {\n                ...\n            },\n                //...\n            }\n        },\n    }\n}\n```\n\n```bash\nnx build my-app\n```\n\n## Examples\n\n{% tabs %}\n{% tab label=\"Add a path to your webpack.config.js file\" %}\n\nYou can configure Webpack using a `webpack.config.js` file. If you do so, you can set the path to this file in your `project.json` file, in the `build` target options:\n\n```json\n//...\n\"my-app\": {\n    \"targets\": {\n        //...\n        \"build\": {\n            \"executor\": \"@nrwl/webpack:webpack\",\n            //...\n            \"options\": {\n                //...\n                \"webpackConfig\": \"apps/my-app/webpack.config.js\"\n            },\n            \"configurations\": {\n                ...\n            }\n        },\n    }\n}\n```\n\nRead more on how to configure Webpack in the [Nx Webpack configuration guide](/packages/webpack/documents/webpack-config-setup).\n\n{% /tab %}\n\n{% tab label=\"Run webpack with `isolatedConfig`\" %}\n\nSetting `isolatedConfig` to `true` in your `project.json` file means that Nx will not apply the Nx webpack plugins automatically. In that case, the Nx plugins need to be applied in the project's `webpack.config.js` file (e.g. `withNx`, `withReact`, etc.). So don't forget to also specify the path to your webpack config file (using the `webpackConfig` option).\n\nRead more on how to configure Webpack in our [Nx Webpack configuration guide](/packages/webpack/documents/webpack-config-setup) an in our [Webpack Plugins guide](/packages/webpack/documents/webpack-plugins).\n\nNote that this is the new default setup for webpack in the latest version of Nx.\n\nSet `isolatedConfig` to `true` in your `project.json` file in the `build` target options like this:\n\n```json\n//...\n\"my-app\": {\n    \"targets\": {\n        //...\n        \"build\": {\n            \"executor\": \"@nrwl/webpack:webpack\",\n            //...\n            \"options\": {\n                //...\n                \"webpackConfig\": \"apps/my-app/webpack.config.js\",\n                \"isolatedConfig\": true\n            },\n            \"configurations\": {\n                ...\n            }\n        },\n    }\n}\n```\n\n{% /tab %}\n\n{% /tabs %}\n",
     "presets": []
   },
   "description": "Run webpack build.",

docs/map.json

@@ -1609,6 +1609,25 @@
             }
           ]
         },
+        {
+          "name": "webpack",
+          "id": "webpack",
+          "description": "Webpack package.",
+          "itemList": [
+            {
+              "name": "Configure webpack on your Nx workspace",
+              "id": "webpack-config-setup",
+              "description": "Configure webpack on your Nx workspace",
+              "file": "shared/packages/webpack/webpack-config-setup"
+            },
+            {
+              "name": "Webpack plugins",
+              "id": "webpack-plugins",
+              "description": "Webpack plugins",
+              "file": "shared/packages/webpack/webpack-plugins"
+            }
+          ]
+        },
         {
           "name": "angular",
           "id": "angular",

docs/shared/packages/webpack/webpack-config-setup.md

@@ -0,0 +1,108 @@
+# Configure webpack on your Nx workspace
+
+You can configure Webpack using a `webpack.config.js` file in your project. You can set the path to this file in your `project.json` file, in the `build` target options:
+
+```json
+//...
+"my-app": {
+    "targets": {
+        //...
+        "build": {
+            "executor": "@nrwl/webpack:webpack",
+            //...
+            "options": {
+                //...
+                "webpackConfig": "apps/my-app/webpack.config.js"
+            },
+            "configurations": {
+                ...
+            }
+        },
+    }
+}
+```
+
+In that file, you can add the necessary configuration for Webpack. You can read more on how to configure webpack in the [Webpack documentation](https://webpack.js.org/concepts/configuration/).
+
+## Using webpack with `isolatedConfig`
+
+Setting `isolatedConfig` to `true` in your `project.json` file means that Nx will not apply the Nx webpack plugins automatically. In that case, the Nx plugins need to be applied in the project's `webpack.config.js` file (e.g. `withNx`, `withReact`, etc.). So don't forget to also specify the path to your webpack config file (using the `webpackConfig` option).
+
+Note that this is the new default setup for webpack in the latest version of Nx.
+
+Set `isolatedConfig` to `true` in your `project.json` file in the `build` target options like this:
+
+```json
+//...
+"my-app": {
+    "targets": {
+        //...
+        "build": {
+            "executor": "@nrwl/webpack:webpack",
+            //...
+            "options": {
+                //...
+                "webpackConfig": "apps/my-app/webpack.config.js",
+                "isolatedConfig": true
+            },
+            "configurations": {
+                ...
+            }
+        },
+    }
+}
+```
+
+Now, you need to manually add the Nx webpack plugins in your `webpack.config.js` file for Nx to work properly. Let's see how to do that.
+
+### Basic configuration for Nx
+
+You should start with a basic webpack configuration for Nx in your project, that looks like this:
+
+```ts
+// apps/my-app/webpack.config.js
+const { composePlugins, withNx } = require('@nrwl/webpack');
+
+module.exports = composePlugins(withNx(), (config, { options, context }) => {
+  // customize webpack config here
+  return config;
+});
+```
+
+The `withNx()` plugin adds the necessary configuration for Nx to work with Webpack. The `composePlugins` function allows you to add other plugins to the configuration.
+
+#### The `composePlugins` function
+
+The `composePlugins` function takes a list of plugins and a function, and returns a webpack `Configuration` object. The `composePlugins` function is an enhanced version of the [webpack configuration function](https://webpack.js.org/configuration/configuration-types/#exporting-a-function), which allows you to add plugins to the configuration, and provides you with a function which accepts two arguments:
+
+1. `config`: The webpack configuration object.
+2. An object with the following properties:
+   - `options`: The options passed to the `@nrwl/webpack:webpack` executor.
+   - `context`: The context passed of the `@nrwl/webpack:webpack` executor.
+
+This gives you the ability to customize the webpack configuration as needed, and make use of the options and context passed to the executor, as well.
+
+### Add configurations for other functionalities
+
+In addition to the basic configuration, you can add configurations for other frameworks or features. The `@nrwl/webpack` package provides plugins such as `withWeb` and `withReact`. This plugins provide features such as TS support, CSS support, JSX support, etc. You can read more about how these plugins work and how to use them in our [Webpack Plugins guide](/packages/webpack/documents/webpack-plugins).
+
+You may still reconfigure everything manually, without using the Nx plugins. However, these plugins ensure that you have the necessary configuration for Nx to work with your project.
+
+Here is an example of a configuration that uses the `withReact` plugin:
+
+```ts
+// apps/my-react-app/webpack.config.js
+const { composePlugins, withNx } = require('@nrwl/webpack');
+const { withReact } = require('@nrwl/react');
+
+// Nx plugins for webpack.
+module.exports = composePlugins(
+  withNx(),
+  withReact(),
+  (config, { options, context }) => {
+    // Update the webpack config as needed here.
+    // e.g. config.plugins.push(new MyPlugin())
+    return config;
+  }
+);
+```

docs/shared/packages/webpack/webpack-plugins.md

@@ -0,0 +1,9 @@
+# Webpack plugins
+
+Coming soon.
+
+## `withNx`
+
+## `withWeb`
+
+## `withReact`