Skip to content

Latest commit

 

History

History
323 lines (256 loc) · 7.73 KB

migration-v5.md

File metadata and controls

323 lines (256 loc) · 7.73 KB

Migration guide

This document serves as a migration guide for [email protected].

⚠ 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.