close
Guide
Config
Plugin
API
Community
Guide
Config
Plugin
API
Community

server.cors

  • Type: boolean | import('cors').CorsOptions
  • Default: false
  • Version: >= 1.1.11

Configure CORS options for the dev server or preview server, based on the cors middleware.

  • true：Enable CORS with default options.
  • false：Disable CORS.
  • object：Enable CORS with the specified options.
TIP

Although cors can be set to true, we recommend setting a specified origin option to prevent untrusted origins from accessing your dev server.

Example

  • Enable CORS:
rsbuild.config.ts
export default {
  server: {
    cors: {
      // Configures the `Access-Control-Allow-Origin` CORS response header
      origin: 'https://example.com',
    },
  },
};
  • Only enable CORS for the dev server:
rsbuild.config.ts
const isDev = process.env.NODE_ENV === 'development';

export default {
  server: {
    cors: isDev ? { origin: 'https://example.com' } : false,
  },
};
  • Disable CORS (default behavior):
rsbuild.config.ts
export default {
  server: {
    cors: false,
  },
};

Options

The cors option can be an object, which is the same as the cors middleware options.

The default configuration is the equivalent of:

const defaultOptions = {
  origin: '*',
  methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
  preflightContinue: false,
  optionsSuccessStatus: 204,
};

origin

  • Type:
type StaticOrigin =
  | boolean
  | string
  | RegExp
  | Array<boolean | string | RegExp>;

type CustomOrigin = (
  requestOrigin: string | undefined,
  callback: (err: Error | null, origin?: StaticOrigin) => void,
) => void;

type Origin = StaticOrigin | CustomOrigin;

The origin option is used to configure the Access-Control-Allow-Origin header:

rsbuild.config.ts
export default {
  server: {
    cors: {
      origin: 'https://example.com',
    },
  },
};

Specify multiple allowed origins using an array:

rsbuild.config.ts
export default {
  server: {
    cors: {
      origin: ['https://example.com', 'https://other.com'],
    },
  },
};

Use a regular expression to allow all matching origins:

rsbuild.config.ts
export default {
  server: {
    cors: {
      origin: /\.example\.com$/,
    },
  },
};

Setting origin to a function allows you to dynamically determine the allowed origin, the function receives two parameters:

  • origin：The origin of the incoming request, undefined if no origin is present.
  • callback：A function to set the allowed origin.
rsbuild.config.ts
export default {
  server: {
    cors: {
      origin: (origin, callback) => {
        // loadMyOrigins is an example call to load a list of origins
        loadMyOrigins((error, origins) => {
          callback(error, origins);
        });
      },
    },
  },
};
ON THIS PAGE