Skip to content

migrate-v1-to-v2.md

Latest commit

 

History

History
275 lines (207 loc) · 7.19 KB

migrate-v1-to-v2.md

File metadata and controls

275 lines (207 loc) · 7.19 KB

@rspack/dev-server Migration Guide (v1 -> v2)

This guide covers breaking changes you need to handle when upgrading @rspack/dev-server from v1 to v2.

Breaking Changes

Drop Node 18 Support

Node.js 18 is no longer supported in v2.

The minimum supported Node.js version is now ^20.19.0 || >=22.12.0.

Drop Rspack v1 Support

@rspack/dev-server v2 is designed to work with Rspack v2. Rspack v1 is no longer supported in v2.

Pure ESM package

@rspack/dev-server is now published as pure ESM package.

Upgraded http-proxy-middleware to v4

http-proxy-middleware has been updated from v2 to v4, with several breaking changes introduced since v3:

  • proxy[].path is removed. Use pathFilter (or context) instead.
{
-  path: '/api',
+  pathFilter: '/api',
}
  • logLevel / logProvider are replaced by logger.
- logLevel: 'warn',
+ logger: console,
  • onProxyReq / onProxyRes / onProxyReqWs are moved to on: { ... }.
- onProxyReq(proxyReq) {
-   proxyReq.setHeader('x-from', 'dev-server');
- },
+ on: {
+   proxyReq(proxyReq) {
+     proxyReq.setHeader('x-from', 'dev-server');
+   },
+ },
  • proxy[].bypass is removed, use pathFilter or router instead.
    • 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.

Refer to the http-proxy-middleware v3 migration guide for details.

Default app now uses connect-next

When devServer.app is omitted, @rspack/dev-server now creates a connect-next app instead of an Express app.

The dev server only needs a minimal middleware pipeline. connect-next is an actively maintained fork of Connect that keeps the same (req, res, next) middleware interface while staying smaller than Express and having fewer dependencies.

If you relied on Express-only APIs on devServer.app, such as app.get(), app.post(), or res.send(), provide your own Express app explicitly:

import express from 'express';

export default {
  devServer: {
    app: async () => express(),
  },
};

Updated chokidar to v5

@rspack/dev-server v2 upgrades the underlying file watcher chokidar from v3 to v5.

One important breaking change in chokidar v4+ is that glob patterns are no longer supported.

If you previously passed glob patterns such as **/*.js or ./directory/**/* to devServer.watchFiles, you can watch a directory and filter with ignored:

// Before
export default {
  devServer: {
    watchFiles: '**/*.js',
  },
};

// After
export default {
  devServer: {
    watchFiles: {
      paths: '.',
      options: {
        ignored: (path, stats) =>
          stats?.isFile() && !path.endsWith('.js'),
      },
    },
  },
};

Or use node:fs/promises to expand the glob first:

import { glob } from 'node:fs/promises';

export default async () => ({
  devServer: {
    watchFiles: await Array.fromAsync(glob('**/*.js')),
  },
});

Removed spdy support

  • server.type: "spdy" is no longer supported.
  • server.options.spdy is no longer supported.

You can switch to server.type: "http2" or "https" instead.

// Before
export default {
  devServer: {
    server: {
      type: 'spdy',
      options: {
        spdy: { protocols: ['h2', 'http/1.1'] },
      },
    },
  },
};

// After
export default {
  devServer: {
    server: {
      type: 'http2', // or 'https'
      options: {},
    },
  },
};

Array.fromAsync() requires Node.js 22+.

Optional selfsigned peer dependency

selfsigned is no longer bundled as a direct dependency of @rspack/dev-server.

If you use server.type: "https" or "http2" without providing your own server.options.key and server.options.cert, the dev server needs selfsigned to generate a local certificate.

Install it in your project when needed:

npm i -D selfsigned@^5.0.0
# or pnpm add -D selfsigned@^5.0.0
# or yarn add -D selfsigned@^5.0.0
# or bun add -D selfsigned@^5.0.0

Removed serve-index support

devServer.static.serveIndex is removed in v2 to reduce third-party dependencies.

If you still need directory listings for a static directory, install serve-index and register it with setupMiddlewares:

npm i -D serve-index
# or pnpm add -D serve-index
# or yarn add -D serve-index
# or bun add -D serve-index
import path from 'node:path';
import serveIndex from 'serve-index';

const publicDirectory = path.join(import.meta.dirname, 'public');

export default {
  devServer: {
    static: {
      directory: publicDirectory,
    },
    setupMiddlewares: (middlewares) => {
      middlewares.push({
        name: 'serve-index',
        // The same as `static.publicPath`
        path: '/',
        middleware: serveIndex(publicDirectory, { icons: true }),
      });

      return middlewares;
    },
  },
};

Removed SockJS support (ws only)

In v2, the following SockJS options are no longer available:

  • webSocketServer: "sockjs"
  • webSocketServer: { type: "sockjs" }
  • client.webSocketTransport: "sockjs"
  • webSocketServer.options.prefix (use path)

Also, SockJS bundle routes were removed.

// Before
export default {
  devServer: {
    webSocketServer: 'sockjs',
    client: {
      webSocketTransport: 'sockjs',
    },
  },
};

// After
export default {
  devServer: {
    webSocketServer: 'ws',
    client: {
      webSocketTransport: 'ws',
    },
  },
};

If you need a non-default transport/server, you can provide a custom implementation path instead of 'sockjs'.

Removed bonjour

Built-in Bonjour support is removed in v2.

If Bonjour/ZeroConf broadcasting is still important for your workflow, consider integrating bonjour-service directly in your app code.

Renamed webpack-dev-server-* to rspack-dev-server-*

If your setup still uses the legacy names, you can update them as follows:

  • Environment variables
    • WEBPACK_DEV_SERVER_BASE_PORT -> RSPACK_DEV_SERVER_BASE_PORT
    • WEBPACK_DEV_SERVER_PORT_RETRY -> RSPACK_DEV_SERVER_PORT_RETRY
    • WEBPACK_SERVE -> RSPACK_SERVE
  • URL query flags
    • webpack-dev-server-hot=false -> rspack-dev-server-hot=false
    • webpack-dev-server-live-reload=false -> rspack-dev-server-live-reload=false
  • Built-in routes
    • /webpack-dev-server/* -> /rspack-dev-server/*
# Before
http://localhost:8080/?webpack-dev-server-hot=false&webpack-dev-server-live-reload=false
GET /webpack-dev-server/invalidate
GET /webpack-dev-server/open-editor?fileName=...

# After
http://localhost:8080/?rspack-dev-server-hot=false&rspack-dev-server-live-reload=false
GET /rspack-dev-server/invalidate
GET /rspack-dev-server/open-editor?fileName=...