Nx with Webpack

Webpack is a static module bundler for modern JavaScript applications. In a Webpack monorepo, Nx brings smart task running and caching to every project.

The @nx/webpack plugin infers tasks that build and serve your projects with webpack, and it provides an executor for SSR.

You can customize your webpack configuration for your projects. Nx also provides a number of webpack plugins for supporting Nx and other frameworks.

Requirements

The @nx/webpack plugin supports the following package versions.

Package	Supported Versions
`webpack`	^5.0.0
`webpack-dev-server`	^5.0.0
`webpack-cli`	^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0

Nx generators install the latest supported versions automatically when scaffolding new projects.

Setting up a new Nx workspace with Webpack

You can create a new workspace that uses Webpack with one of the following commands:

Generate a new standalone React app set up with Webpack

npx create-nx-workspace@latest --preset=react-standalone --bundler=webpack

Generate a new React monorepo set up with Webpack

npx create-nx-workspace@latest --preset=react-monorepo --bundler=webpack

Installation

In any Nx workspace, you can install @nx/webpack by running the following command:

nx add @nx/webpack

This will install the correct version of @nx/webpack.

How @nx/webpack infers tasks

The @nx/webpack plugin will create a task for any project that has a Webpack configuration file present. Any of the following files will be recognized as a Webpack configuration file:

webpack.config.js
webpack.config.ts
webpack.config.mjs
webpack.config.cjs

The configuration directory must also contain a package.json or project.json.

View inferred tasks

To view inferred tasks for a project, open the project details view in Nx Console or run nx show project my-project --web in the command line.

@nx/webpack configuration

The @nx/webpack/plugin is configured in the plugins array in nx.json.

{
  "plugins": [
    {
      "plugin": "@nx/webpack/plugin",
      "options": {
        "buildTargetName": "build",
        "previewTargetName": "preview",
        "serveTargetName": "serve",
        "serveStaticTargetName": "serve-static",
        "buildDepsTargetName": "build-deps",
        "watchDepsTargetName": "watch-deps"
      }
    }
  ]
}

Option	Default	Inferred behavior
`buildTargetName`	`build`	Runs and caches `webpack-cli build` with its configured outputs.
`serveTargetName`	`serve`	Runs `webpack-cli serve` continuously in development mode.
`previewTargetName`	`preview`	Runs `webpack-cli serve` continuously in production mode.
`serveStaticTargetName`	`serve-static`	Serves the build output continuously after the build task.
`buildDepsTargetName`	`build-deps`	Name of the dependency build task.
`watchDepsTargetName`	`watch-deps`	Name of the dependency watch task.

The build task depends on builds of project dependencies. When TypeScript project references are enabled, the tasks also run the TypeScript sync generator.

Use include and exclude glob patterns on the plugin entry to scope inference. A target defaults plugin filter must use the exact identifier @nx/webpack/plugin.

Wait for the dev server to be ready

The inferred serve and preview targets come with a readyWhen check, so a task can wait until the dev server accepts requests instead of only until it has started. When the webpack config sets devServer and loads NxAppWebpackPlugin, the check waits for the plugin to report the server's address once it listens. In a config without NxAppWebpackPlugin, add new NxReadySignalPlugin() from @nx/webpack/ready-signal to plugins instead. The report carries the port the server actually uses, so the check is right however the port was chosen. The signal applies only when exactly one config sets devServer. When several configs set it, Nx uses the config-reading check below even if each one loads a signal plugin.

Without either plugin, the check reads the webpack config when the task runs instead, in the task's environment and with its options. That covers .env files and --port or --host flags. It works out the port the way webpack-cli serve does, from the --port flag, devServer.port, WEBPACK_DEV_SERVER_BASE_PORT, or 8080, and waits for it. When the server picks its own port (a devServer.port of 0 or "auto") or listens on a socket instead of a port (devServer.ipc), there's nothing to wait for, and the target counts as ready once it has started. The serve-static target's file server reports its address once it listens.

A dependent task starts as soon as the server task has started, unless its dependsOn entry sets waitFor to ready:

{
  "targets": {
    "e2e": {
      "dependsOn": [
        { "projects": "myapp", "target": "serve", "waitFor": "ready" }
      ]
    }
  }
}

The waiting task gets the server's address in the NX_READY_URL environment variable, when exactly one target it waits for reported one. A readyWhen on the target in targetDefaults or in the project configuration replaces the inferred check, and null turns it off. For the other checks, see wait for a continuous task to be ready. For signaling from your own server, see signal readiness from the task.

Generate a new project using Webpack

You can generate a React application or a Web application that uses Webpack in an existing Nx workspace. The @nx/react:app, @nx/node:app and @nx/web:app generators accept the bundler option, where you can pass webpack. This will generate a new application configured to use Webpack, and it will also install all the necessary dependencies, including the @nx/webpack plugin.

To generate a React application using Webpack, run the following:

nx g @nx/react:app apps/my-app --bundler=webpack

To generate a Node application using Webpack, run the following:

nx g @nx/node:app apps/my-app --bundler=webpack

To generate a Web application using Webpack, run the following:

nx g @nx/web:app apps/my-app --bundler=webpack

Set up CI for your Webpack monorepo

In CI, Nx runs nx affected to rebuild and retest only the projects a change touches, and caches results to skip repeated work.

For a complete pipeline, see Set up CI.