close
  • English

      • server.setup

      • Type:
      type MaybePromise<T> = T | Promise<T>;

type ServerSetupFn = (
  context: ServerSetupContext,
) => MaybePromise<(() => MaybePromise<void>) | void>;

type ServerSetup = ServerSetupFn | ServerSetupFn[];
      • Default: undefined
      • Version: >= 2.0.0

      Run setup logic for both dev and preview servers.

      Primarily used to register middleware, and can also run other startup tasks. Similar to onBeforeStartDevServer and onBeforeStartProdServer hooks.

      Basic usage

      server.setup receives a context object:

      type ServerSetupContext =
  | {
      action: 'dev';
      server: RsbuildDevServer;
      environments: Record<string, EnvironmentContext>;
    }
  | {
      action: 'preview';
      server: RsbuildProdServer;
      environments: Record<string, EnvironmentContext>;
    };
      • context.action: 'dev' or 'preview'.
      • context.server.middlewares: the connect app instance. Use middlewares.use(...) to register middleware.
      • context.environments: environment contexts of all environments.

      server.setup is mainly for registering middleware, and can also run other startup tasks. It is similar to onBeforeStartDevServer and onBeforeStartProdServer, but configured in rsbuild.config.ts.

      The setup function runs before Rsbuild registers built-in middlewares, so middlewares added in setup run earlier than built-ins. It can return a callback, and that callback runs after built-in middlewares are registered.

      rsbuild.config.ts
      export default {
  server: {
    setup: ({ server }) => {
      server.middlewares.use((req, res, next) => {
        console.log('first');
        next();
      });
    },
  },
};

      Post callback

      Use a returned callback to register middleware after built-in middlewares:

      rsbuild.config.ts
      export default {
  server: {
    setup: ({ server }) => {
      server.middlewares.use((req, _res, next) => {
        if (req.url === '/api/before') {
          console.log('before built-ins');
        }
        next();
      });

      return () => {
        server.middlewares.use((req, _res, next) => {
          if (req.url === '/api/after') {
            console.log('after built-ins');
          }
          next();
        });
      };
    },
  },
};

      Multiple functions

      server.setup also supports passing an array:

      rsbuild.config.ts
      export default {
  server: {
    setup: [
      ({ server }) => {
        server.middlewares.use(authMiddleware);
      },
      ({ server }) => {
        server.middlewares.use(logMiddleware);
      },
    ],
  },
};

      Dev-only APIs

      In dev mode, you can access dev-only capabilities such as server.sockWrite:

      rsbuild.config.ts
      export default {
  server: {
    setup: (context) => {
      if (context.action !== 'dev') {
        return;
      }

      context.server.middlewares.use((_req, _res, next) => {
        next();
      });

      context.server.sockWrite('static-changed');
    },
  },
};