migration-v5.md

Migration guide

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

⚠ BREAKING CHANGES

• Minimum supported Node.js version is 18.12.0.

• Minimum supported webpack version is 5.0.0.

• Minimum compatible webpack-cli version is 5.0.0 but we recommend using the latest version.

• The http2 and https options were removed in favor of the server option.

  v4:

  module.exports = {
    devServer: {
      http2: true,
      https: {
        ca: "./path/to/server.pem",
        pfx: "./path/to/server.pfx",
        key: "./path/to/server.key",
        cert: "./path/to/server.crt",
        passphrase: "webpack-dev-server",
        requestCert: true,
      },
    },
  };

  v5:

  module.exports = {
    //...
    devServer: {
      server: {
        type: "spdy", // or use 'https'
        options: {
          ca: "./path/to/server.pem",
          pfx: "./path/to/server.pfx",
          key: "./path/to/server.key",
          cert: "./path/to/server.crt",
          passphrase: "webpack-dev-server",
          requestCert: true,
        },
      },
    },
  };

• The server.options.cacert option was removed in favor of the server.options.ca option.

  v4:

  module.exports = {
    //...
    devServer: {
      server: {
        type: "https", // or use 'https'
        options: {
          cacert: "./path/to/server.pem",
        },
      },
    },
  };

  v5:

  module.exports = {
    //...
    devServer: {
      server: {
        type: "https",
        options: {
          ca: "./path/to/server.pem",
        },
      },
    },
  };

• The onAfterSetupMiddleware and onBeforeSetupMiddleware options were removed in favor of the setupMiddlewares option.

  v4:

  module.exports = {
    //...
    devServer: {
      onAfterSetupMiddleware: function (devServer) {
        if (!devServer) {
          throw new Error("webpack-dev-server is not defined");
        }
  
        devServer.app.get("/some/after-path", function (req, res) {
          res.json({ custom: "response" });
        });
      },
      onBeforeSetupMiddleware: function (devServer) {
        if (!devServer) {
          throw new Error("webpack-dev-server is not defined");
        }
  
        devServer.app.get("/some/before-path", function (req, res) {
          res.json({ custom: "response" });
        });
      },
    },
  };

  v5:

  module.exports = {
    // ...
    devServer: {
      setupMiddlewares: (middlewares, devServer) => {
        if (!devServer) {
          throw new Error("webpack-dev-server is not defined");
        }
  
        devServer.app.get("/setup-middleware/some/path", (_, response) => {
          response.send("setup-middlewares option GET");
        });
  
        // Use the `unshift` method if you want to run a middleware before all other middlewares
        // or when you are migrating from the `onBeforeSetupMiddleware` option
        middlewares.unshift({
          name: "first-in-array",
          // `path` is optional
          path: "/some/before-path",
          middleware: (req, res) => {
            res.send("Foo!");
          },
        });
  
        // Use the `push` method if you want to run a middleware after all other middlewares
        // or when you are migrating from the `onAfterSetupMiddleware` option
        middlewares.push({
          name: "hello-world-test-one",
          // `path` is optional
          path: "/some/after-bar",
          middleware: (req, res) => {
            res.send("Foo Bar!");
          },
        });
  
        middlewares.push((req, res) => {
          res.send("Hello World!");
        });
  
        return middlewares;
      },
    },
  };

• The proxy option's schema was updated to accept only an array.

v4:

module.exports = {
  //...
  devServer: {
    proxy: {
      "/api": {
        target: "http://localhost:3000",
        changeOrigin: true,
      },
    },
  },
};

v5:

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ["/api"],
        target: "http://localhost:3000",
        changeOrigin: true,
      },
    ],
  },
};

• The --open-app cli option was removed in favor of the --open-app-name option.

• The --web-socket-server cli option was removed in favor of the --web-socket-server-type option.

• The magicHtml option was removed without replacement.

• The value of the WEBPACK_SERVE environment variable was changed from true(boolean) to 'true' (string).

• webpack-dev-middleware was update to v7.

• The constructor arguments were changed, now the first argument is dev server options, the second is compiler.

  v4:

  const devServerOptions = { host: "127.0.0.1", port: 8080 };
  const devServer = new Server(compiler, devServerOptions);

  v5:

  const devServerOptions = { host: "127.0.0.1", port: 8080 };
  const devServer = new Server(devServerOptions, compiler);

• The listen method was removed in favor the async start or the startCallback methods

  v4:

  const devServerOptions = { host: "127.0.0.1", port: 8080 };
  const devServer = new Server(compiler, devServerOptions);
  
  devServer.listen(devServerOptions.host, devServerOptions.port, () => {
    console.log("Running");
  });

  v5:

  const devServerOptions = { host: "127.0.0.1", port: 8080 };
  const devServer = new Server(devServerOptions, compiler);
  
  (async () => {
    await devServer.start();
  
    console.log("Running");
  })();

  const devServerOptions = { host: "127.0.0.1", port: 8080 };
  const devServer = new Server(devServerOptions, compiler);
  
  devServer.startCallback(() => {
    console.log("Running");
  });

• The close method was removed in favor the async stop or the stopCallback methods.

  v4:

  const devServerOptions = { host: "127.0.0.1", port: 8080 };
  const devServer = new Server(compiler, devServerOptions);
  
  devServer.listen(devServerOptions.host, devServerOptions.port, () => {
    console.log("Running");
  
    devServer.close(() => {
      console.log("Closed");
    });
  });

  v5:

  const devServerOptions = { host: "127.0.0.1", port: 8080 };
  const devServer = new Server(devServerOptions, compiler);
  
  (async () => {
    await devServer.start();
  
    console.log("Running");
  
    await devServer.stop();
  
    console.log("Closed");
  })();

  const devServerOptions = { host: "127.0.0.1", port: 8080 };
  const devServer = new Server(devServerOptions, compiler);
  
  devServer.startCallback(() => {
    console.log("Running");
  
    devServer.stopCallback(() => {
      console.log("Closed");
    });
  });

• The content-changed method was removed in favor of the static-changed method from onSocketMessage.

  v4:

  onSocketMessage["content-changed"]();

  v5:

  onSocketMessage["static-changed"]();

Bug Fixes

• Clean close event listeners on socket server after generating new proxy config.
• Improve error handling for WebsocketServer.
• Set WEBPACK_SERVE to string value 'true'.
• Show warning using custom hostname and port with sockjs.

Deprecations

• The bypass option is deprecated for proxy in favor of the router and the context options. Read more here.