Skip to content

migration-v5.md

Latest commit

 

History

History
319 lines (252 loc) · 7.64 KB

migration-v5.md

File metadata and controls

319 lines (252 loc) · 7.64 KB

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(devServer) {
      if (!devServer) {
        throw new Error("webpack-dev-server is not defined");
      }

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

      devServer.app.get("/some/before-path", (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);

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);

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.