feat(webpack): remove isolatedConfig option for @nx/webpack:webpack (#30910)

This PR removes the `isolatedConfig` option that has been deprecated
since v17. Back when it was deprecated, we had a migration to remove the
option and set `webpackConfig` with a generate config file that matches
the executor's built-in behavior. Now that we're removing the option, a
similar migration is added to generate the config files for any projects
that skipped the migration the first time.

docs/generated/manifests/nx-api.json

@@ -5366,6 +5366,16 @@
       }
     },
     "migrations": {
+      "/nx-api/webpack/migrations/update-21-0-0-remove-isolated-config": {
+        "description": "Remove isolatedConfig option for @nx/webpack:webpack",
+        "file": "generated/packages/webpack/migrations/update-21-0-0-remove-isolated-config.json",
+        "hidden": false,
+        "name": "update-21-0-0-remove-isolated-config",
+        "version": "21.0.0-beta.11",
+        "originalFilePath": "/packages/webpack",
+        "path": "/nx-api/webpack/migrations/update-21-0-0-remove-isolated-config",
+        "type": "migration"
+      },
       "/nx-api/webpack/migrations/20.7.1-package-updates": {
         "description": "",
         "file": "generated/packages/webpack/migrations/20.7.1-package-updates.json",

docs/generated/packages-metadata.json

@@ -5329,6 +5329,16 @@
       }
     ],
     "migrations": [
+      {
+        "description": "Remove isolatedConfig option for @nx/webpack:webpack",
+        "file": "generated/packages/webpack/migrations/update-21-0-0-remove-isolated-config.json",
+        "hidden": false,
+        "name": "update-21-0-0-remove-isolated-config",
+        "version": "21.0.0-beta.11",
+        "originalFilePath": "/packages/webpack",
+        "path": "webpack/migrations/update-21-0-0-remove-isolated-config",
+        "type": "migration"
+      },
       {
         "description": "",
         "file": "generated/packages/webpack/migrations/20.7.1-package-updates.json",

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

@@ -330,12 +330,6 @@
         "type": "boolean",
         "description": "Generates a 'stats.json' file which can be analyzed using tools such as: 'webpack-bundle-analyzer' or `<https://webpack.github.io/analyse>`."
       },
-      "isolatedConfig": {
-        "type": "boolean",
-        "description": "Do not apply Nx webpack plugins automatically. Plugins need to be applied in the project's webpack.config.js file (e.g. withNx, withReact, etc.).",
-        "default": true,
-        "x-deprecated": "Automatic configuration of Webpack is deprecated in favor of an explicit 'webpack.config.js' file. This option will be removed in Nx 20. See https://nx.dev/recipes/webpack/webpack-config-setup."
-      },
       "standardWebpackConfigFunction": {
         "type": "boolean",
         "description": "Set to true if the webpack config exports a standard webpack function, not an Nx-specific one. See: https://webpack.js.org/configuration/configuration-types/#exporting-a-function",

docs/generated/packages/webpack/migrations/update-21-0-0-remove-isolated-config.json

@@ -0,0 +1,13 @@
+{
+  "name": "update-21-0-0-remove-isolated-config",
+  "cli": "nx",
+  "version": "21.0.0-beta.11",
+  "description": "Remove isolatedConfig option for @nx/webpack:webpack",
+  "implementation": "/packages/webpack/src/migrations/update-21-0-0/remove-isolated-config.ts",
+  "aliases": [],
+  "hidden": false,
+  "path": "/packages/webpack",
+  "schema": null,
+  "type": "migration",
+  "examplesFile": "#### Remove `isolatedConfig` option\n\nThe `isolatedConfig` option is no longer supported by the `@nx/webpack:webpack` executor. Previously, setting `isolatedConfig: false` allowed you to use the executor's built-in Webpack configuration.\n\nIf this option is set in `project.json`, then it will be removed in favor of an explicit `webpackConfig` file. The Webpack configuration file matches the previous built-in configuration of the `@nx/webpack:webpack` executor.\n\n#### Sample Code Changes\n\n{% tabs %}\n{% tab label=\"Before\" %}\n\n```json {% fileName=\"project.json\" %}\n{\n  \"targets\": {\n    \"build\": {\n      \"executor\": \"@nx/webpack:webpack\",\n      \"options\": {\n        \"isolatedConfig\": false\n      }\n    }\n  }\n}\n```\n\n{% /tab %}\n{% tab label=\"After\" %}\n\n```json {% highlightLines=[6] fileName=\"project.json\" %}\n{\n  \"targets\": {\n    \"build\": {\n      \"executor\": \"@nx/webpack:webpack\",\n      \"options\": {\n        \"webpackConfig\": \"apps/myapp/webpack.config.js\"\n      }\n    }\n  }\n}\n```\n\n{% /tab %}\n{% /tabs %}\n"
+}

packages/webpack/migrations.json

@@ -5,6 +5,12 @@
       "version": "19.6.3-beta.0",
       "description": "Migrate proxy config files to match new format from webpack-dev-server v5.",
       "implementation": "./src/migrations/update-19-6-3/proxy-config"
+    },
+    "update-21-0-0-remove-isolated-config": {
+      "cli": "nx",
+      "version": "21.0.0-beta.11",
+      "description": "Remove isolatedConfig option for @nx/webpack:webpack",
+      "implementation": "./src/migrations/update-21-0-0/remove-isolated-config"
     }
   },
   "packageJsonUpdates": {

packages/webpack/src/executors/webpack/schema.d.ts

@@ -47,9 +47,6 @@ export interface WebpackExecutorOptions {
   extractLicenses?: boolean;
   fileReplacements?: FileReplacement[];
   generatePackageJson?: boolean;
-  // TODO(v21): Remove this option
-  /** @deprecated set webpackConfig and provide an explicit webpack.config.js file (See: https://nx.dev/recipes/webpack/webpack-config-setup) */
-  isolatedConfig?: boolean;
   standardWebpackConfigFunction?: boolean;
   main?: string;
   memoryLimit?: number;

packages/webpack/src/executors/webpack/schema.json

@@ -254,12 +254,6 @@
       "type": "boolean",
       "description": "Generates a 'stats.json' file which can be analyzed using tools such as: 'webpack-bundle-analyzer' or `<https://webpack.github.io/analyse>`."
     },
-    "isolatedConfig": {
-      "type": "boolean",
-      "description": "Do not apply Nx webpack plugins automatically. Plugins need to be applied in the project's webpack.config.js file (e.g. withNx, withReact, etc.).",
-      "default": true,
-      "x-deprecated": "Automatic configuration of Webpack is deprecated in favor of an explicit 'webpack.config.js' file. This option will be removed in Nx 20. See https://nx.dev/recipes/webpack/webpack-config-setup."
-    },
     "standardWebpackConfigFunction": {
       "type": "boolean",
       "description": "Set to true if the webpack config exports a standard webpack function, not an Nx-specific one. See: https://webpack.js.org/configuration/configuration-types/#exporting-a-function",

packages/webpack/src/executors/webpack/webpack.impl.ts

@@ -35,12 +35,6 @@ async function getWebpackConfigs(
   options: NormalizedWebpackExecutorOptions,
   context: ExecutorContext
 ): Promise<Configuration | Configuration[]> {
-  if (options.isolatedConfig && !options.webpackConfig) {
-    throw new Error(
-      `Using "isolatedConfig" without a "webpackConfig" is not supported.`
-    );
-  }
-
   let userDefinedWebpackConfig = null;
   if (options.webpackConfig) {
     userDefinedWebpackConfig = resolveUserDefinedWebpackConfig(
@@ -53,11 +47,7 @@ async function getWebpackConfigs(
     }
   }
 
-  const config = options.isolatedConfig
+  const config = {};
-    ? {}
-    : (options.target === 'web'
-        ? composePluginsSync(withNx(options), withWeb(options))
-        : withNx(options))({}, { options, context });
 
   if (
     typeof userDefinedWebpackConfig === 'function' &&

packages/webpack/src/generators/convert-to-inferred/utils/build-post-target-transformer.ts

@@ -140,13 +140,6 @@ function extractPluginOptions(
         });
       }
       delete options.memoryLimit;
-    } else if (key === 'isolatedConfig') {
-      context.logger.addLog({
-        executorName: '@nx/webpack:webpack',
-        log: `The 'isolatedConfig' option is deprecated and not supported by the NxAppWebpackPlugin. It was removed from your project configuration.`,
-        project: context.projectName,
-      });
-      delete options.isolatedConfig;
     } else if (key === 'standardWebpackConfigFunction') {
       delete options.standardWebpackConfigFunction;
     } else {

packages/webpack/src/migrations/update-21-0-0/remove-isolated-config.md

@@ -0,0 +1,42 @@
+#### Remove `isolatedConfig` option
+
+The `isolatedConfig` option is no longer supported by the `@nx/webpack:webpack` executor. Previously, setting `isolatedConfig: false` allowed you to use the executor's built-in Webpack configuration.
+
+If this option is set in `project.json`, then it will be removed in favor of an explicit `webpackConfig` file. The Webpack configuration file matches the previous built-in configuration of the `@nx/webpack:webpack` executor.
+
+#### Sample Code Changes
+
+{% tabs %}
+{% tab label="Before" %}
+
+```json {% fileName="project.json" %}
+{
+  "targets": {
+    "build": {
+      "executor": "@nx/webpack:webpack",
+      "options": {
+        "isolatedConfig": false
+      }
+    }
+  }
+}
+```
+
+{% /tab %}
+{% tab label="After" %}
+
+```json {% highlightLines=[6] fileName="project.json" %}
+{
+  "targets": {
+    "build": {
+      "executor": "@nx/webpack:webpack",
+      "options": {
+        "webpackConfig": "apps/myapp/webpack.config.js"
+      }
+    }
+  }
+}
+```
+
+{% /tab %}
+{% /tabs %}

packages/webpack/src/migrations/update-21-0-0/remove-isolated-config.spec.ts

@@ -0,0 +1,111 @@
+import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
+import {
+  addProjectConfiguration,
+  readProjectConfiguration,
+  Tree,
+} from '@nx/devkit';
+import update from './remove-isolated-config';
+
+describe('21.0.0 - remove isolatedConfig option', () => {
+  let tree: Tree;
+
+  beforeEach(async () => {
+    tree = createTreeWithEmptyWorkspace();
+  });
+
+  it('should create webpack.config.js for projects that did not set webpackConfig', async () => {
+    addProjectConfiguration(tree, 'myapp', {
+      root: 'apps/myapp',
+      targets: {
+        build: {
+          executor: '@nx/webpack:webpack',
+          options: {
+            // This option will be removed
+            isolatedConfig: false,
+          },
+        },
+      },
+    });
+
+    await update(tree);
+
+    const project = readProjectConfiguration(tree, 'myapp');
+    expect(tree.read('apps/myapp/webpack.config.js', 'utf-8'))
+      .toMatchInlineSnapshot(`
+      "const { composePlugins, withNx } = require('@nx/webpack');
+
+      // Nx plugins for webpack.
+      module.exports = composePlugins(withNx(), (config) => {
+        // Note: This was added by an Nx migration. Webpack builds are required to have a corresponding Webpack config file.
+        // See: https://nx.dev/recipes/webpack/webpack-config-setup
+        return config;
+      });
+      "
+    `);
+    expect(project.targets.build.options).toEqual({
+      webpackConfig: 'apps/myapp/webpack.config.js',
+    });
+  });
+
+  it('should create webpack.config.js for projects using `target: web`', async () => {
+    addProjectConfiguration(tree, 'myapp', {
+      root: 'apps/myapp',
+      targets: {
+        build: {
+          executor: '@nx/webpack:webpack',
+          options: {
+            target: 'web',
+            // This option will be removed
+            isolatedConfig: false,
+          },
+        },
+      },
+    });
+
+    await update(tree);
+
+    const project = readProjectConfiguration(tree, 'myapp');
+    expect(tree.read('apps/myapp/webpack.config.js', 'utf-8'))
+      .toMatchInlineSnapshot(`
+      "const { composePlugins, withNx, withWeb } = require('@nx/webpack');
+
+      // Nx plugins for webpack.
+      module.exports = composePlugins(withNx(), withWeb(), (config) => {
+        // Note: This was added by an Nx migration. Webpack builds are required to have a corresponding Webpack config file.
+        // See: https://nx.dev/recipes/webpack/webpack-config-setup
+        return config;
+      });
+      "
+    `);
+    expect(project.targets.build.options).toEqual({
+      target: 'web',
+      webpackConfig: 'apps/myapp/webpack.config.js',
+    });
+  });
+
+  it('should not create webpack.config.js when webpackConfig is already set', async () => {
+    tree.write(
+      `apps/myapp/webpack.config.js`,
+      `
+      module.exports = { /* CUSTOM */ };
+    `
+    );
+    addProjectConfiguration(tree, 'myapp', {
+      root: 'apps/myapp',
+      targets: {
+        build: {
+          executor: '@nx/webpack:webpack',
+          options: {
+            webpackConfig: 'apps/myapp/webpack.config.js',
+          },
+        },
+      },
+    });
+
+    await update(tree);
+
+    expect(tree.read('apps/myapp/webpack.config.js', 'utf-8')).toContain(
+      '/* CUSTOM */'
+    );
+  });
+});

packages/webpack/src/migrations/update-21-0-0/remove-isolated-config.ts

@@ -0,0 +1,60 @@
+import {
+  formatFiles,
+  readProjectConfiguration,
+  Tree,
+  updateProjectConfiguration,
+} from '@nx/devkit';
+import { forEachExecutorOptions } from '@nx/devkit/src/generators/executor-options-utils';
+import { WebpackExecutorOptions } from '../../executors/webpack/schema';
+
+export default async function (tree: Tree) {
+  forEachExecutorOptions<WebpackExecutorOptions>(
+    tree,
+    '@nx/webpack:webpack',
+    (
+      options: WebpackExecutorOptions,
+      projectName: string,
+      targetName: string,
+      configurationName: string
+    ) => {
+      // Only handle webpack config for default configuration
+      if (configurationName) return;
+
+      const projectConfiguration = readProjectConfiguration(tree, projectName);
+
+      if (!options.webpackConfig) {
+        delete options['isolatedConfig'];
+        options.webpackConfig = `${projectConfiguration.root}/webpack.config.js`;
+        tree.write(
+          options.webpackConfig,
+          options.target === 'web'
+            ? `
+const { composePlugins, withNx, withWeb } = require('@nx/webpack');
+
+// Nx plugins for webpack.
+module.exports = composePlugins(withNx(), withWeb(), (config) => {
+  // Note: This was added by an Nx migration. Webpack builds are required to have a corresponding Webpack config file.
+  // See: https://nx.dev/recipes/webpack/webpack-config-setup
+  return config;
+});
+`
+            : `
+const { composePlugins, withNx } = require('@nx/webpack');
+
+// Nx plugins for webpack.
+module.exports = composePlugins(withNx(), (config) => {
+  // Note: This was added by an Nx migration. Webpack builds are required to have a corresponding Webpack config file.
+  // See: https://nx.dev/recipes/webpack/webpack-config-setup
+  return config;
+});
+        `
+        );
+
+        projectConfiguration.targets[targetName].options = options;
+        updateProjectConfiguration(tree, projectName, projectConfiguration);
+      }
+    }
+  );
+
+  await formatFiles(tree);
+}