migration-v6.md

Migration guide

This document serves as a migration guide for webpack-dev-server@6.0.0.

⚠ Breaking Changes

• Minimum supported Node.js version is 22.15.0.

• Minimum supported webpack version is 5.101.0.

• The package is now published as ESM-only. Prefer import syntax. CommonJS consumers can still load it via require(esm), which is enabled by default in the supported Node.js versions (>= 22.15.0).

• webpack-dev-middleware has been upgraded to v8. The most notable change for consumers is that server.middleware.getFilenameFromUrl() is now asynchronous and resolves to an object { filename, extra: { stats, outputFileSystem } } instead of returning the filename synchronously. See the webpack-dev-middleware v8 release notes for the full list of changes.

• The bundled Express has been upgraded to v5. This affects setupMiddlewares, the app option, and any custom middleware integration. Notably: path matching no longer supports the bare * wildcard (use *splat or named parameters), req.query is no longer mutable, and rejected promises in middleware are now forwarded to error handlers automatically. See the Express 5 migration guide for the full list of breaking changes.

• Support for SockJS in the WebSocket transport has been removed. Now, only native WebSocket is supported, or custom client and server implementations can be used.

• The options for passing to the proxy have changed. Please refer to the http-proxy-middleware migration guide for details.

• Remove support for the spdy server type.Use the http2 server type instead; however, since Express does not work correctly with it, a custom server (e.g., Connect or Hono) should be used.

  v4:

  module.exports = {
    // ...
    devServer: {
      server: "spdy",
    },
  };

  v5:

  const connect = require("connect");
  
  module.exports = {
    // ...
    devServer: {
      server: {
        server: "http2",
        app: () => connect(),
      },
    },
  };

• Now, webpack-dev-server adds WebSocket communication only when the target is set to a web-compatible environment. Previously, it also injected WebSocket communication if resolve contained a conditionNames entry with browser or if externalsPresets.web existed.

• When retrieving the configuration in a multi-compiler setup, it will look for one that has a target compatible with a web environment. If it doesn’t find one, it will fall back to the first compiler found by webpack.

Deprecations

• The static methods internalIP and internalIPSync were removed. Use findIp instead.

  v4:

  const ip = Server.internalIP("v4");

  v5:

  const ip = Server.findIp("v4", true);

• Support for webpack-dev-server using CLI flags has been removed. Please use the latest version of webpack-cli.

• The bypass function in the proxy configuration was removed. Use the pathFilter and router for similar functionality. See the example below.

  v4:

  module.exports = {
    // ...
    devServer: {
      proxy: [
        {
          context: "/api",
          bypass(req, res, proxyOptions) {
            if (req.url.startsWith("/api/special")) {
              return "/special.html";
            }
          },
        },
      ],
    },
  };

  v5:

  module.exports = {
    // ...
    devServer: {
      proxy: [
        {
          pathFilter: "/api/special",
          router: () => "http://localhost:3000", // Original Server
          pathRewrite: () => "/special.html",
        },
      ],
    },
  };

  When bypass was used and that function returned a boolean, it would automatically result in a 404 request. This can’t be achieved in a similar way now, or, if it returned a string, you can do what was done in the example above.

  bypass also allowed sending data; this can no longer be done. If you really need to do it, you’d have to create a new route in the proxy that sends the same data, or alternatively create a new route on the main server and, following the example above, send the data you wanted.