fix: correct proxy options type (#3352)

packages/core/src/index.ts

@@ -114,8 +114,8 @@ export type {
   PostCSSLoaderOptions,
   PostCSSPlugin,
   PreconnectOption,
+  ProxyConfig,
   ProxyOptions,
-  ProxyDetail,
   PrintUrls,
   PublicDir,
   PublicDirOptions,

packages/core/src/server/proxy.ts

@@ -2,21 +2,21 @@ import type { RequestHandler } from 'http-proxy-middleware';
 import { logger } from '../logger';
 import type {
   RequestHandler as Middleware,
-  ProxyDetail,
+  ProxyConfig,
   ProxyOptions,
 } from '../types';
 import type { UpgradeEvent } from './helper';
 
-function formatProxyOptions(proxyOptions: ProxyOptions) {
-  const ret: ProxyDetail[] = [];
+function formatProxyOptions(proxyOptions: ProxyConfig) {
+  const ret: ProxyOptions[] = [];
 
   if (Array.isArray(proxyOptions)) {
     ret.push(...proxyOptions);
   } else if ('target' in proxyOptions) {
     ret.push(proxyOptions);
   } else {
     for (const [context, options] of Object.entries(proxyOptions)) {
-      const opts: ProxyDetail = {
+      const opts: ProxyOptions = {
         context,
         changeOrigin: true,
         logLevel: 'warn',
@@ -40,23 +40,23 @@ function formatProxyOptions(proxyOptions: ProxyOptions) {
 }
 
 export const createProxyMiddleware = async (
-  proxyOptions: ProxyOptions,
+  proxyOptions: ProxyConfig,
 ): Promise<{
   middlewares: Middleware[];
   upgrade: UpgradeEvent;
 }> => {
   // If it is not an array, it may be an object that uses the context attribute
   // or an object in the form of { source: ProxyDetail }
-  const formattedOptionsList = formatProxyOptions(proxyOptions);
+  const formattedOptions = formatProxyOptions(proxyOptions);
   const proxyMiddlewares: RequestHandler[] = [];
   const middlewares: Middleware[] = [];
 
-  const { createProxyMiddleware: baseCreateProxyMiddleware } = await import(
+  const { createProxyMiddleware: baseMiddleware } = await import(
     'http-proxy-middleware'
   );
 
-  for (const opts of formattedOptionsList) {
-    const proxyMiddleware = baseCreateProxyMiddleware(opts.context!, opts);
+  for (const opts of formattedOptions) {
+    const proxyMiddleware = baseMiddleware(opts.context!, opts);
 
     const middleware: Middleware = async (req, res, next) => {
       const bypassUrl =

packages/core/src/types/config.ts

@@ -14,7 +14,7 @@ import type {
 } from '@rspack/core';
 import type { WatchOptions } from 'chokidar';
 import type {
-  Options as BaseProxyOptions,
+  Options as HttpProxyOptions,
   Filter as ProxyFilter,
 } from 'http-proxy-middleware';
 import type RspackChain from 'rspack-chain';
@@ -250,20 +250,32 @@ export interface NormalizedSourceConfig extends SourceConfig {
 
 export type HtmlFallback = false | 'index';
 
-export type ProxyDetail = BaseProxyOptions & {
-  bypass?: (
-    req: IncomingMessage,
-    res: ServerResponse,
-    proxyOptions: ProxyOptions,
-  ) => string | undefined | null | boolean;
+export type ProxyBypass = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  proxyOptions: ProxyOptions,
+) => string | undefined | null | boolean;
+
+export type ProxyOptions = HttpProxyOptions & {
+  /**
+   * Bypass the proxy based on the return value of a function.
+   * - Return `null` or `undefined` to continue processing the request with proxy.
+   * - Return `true` to continue processing the request without proxy.
+   * - Return `false` to produce a 404 error for the request.
+   * - Return a path to serve from, instead of continuing to proxy the request.
+   */
+  bypass?: ProxyBypass;
+  /**
+   * Used to proxy multiple specified paths to the same target.
+   */
   context?: ProxyFilter;
 };
 
-export type ProxyOptions =
+export type ProxyConfig =
   | Record<string, string>
-  | Record<string, ProxyDetail>
-  | ProxyDetail[]
-  | ProxyDetail;
+  | Record<string, ProxyOptions>
+  | ProxyOptions[]
+  | ProxyOptions;
 
 export type HistoryApiFallbackContext = {
   match: RegExpMatchArray;
@@ -360,7 +372,7 @@ export interface ServerConfig {
   /**
    * Configure proxy rules for the dev server or preview server to proxy requests to the specified service.
    */
-  proxy?: ProxyOptions;
+  proxy?: ProxyConfig;
   /**
    * Whether to throw an error when the port is occupied.
    */

website/docs/en/config/server/proxy.mdx

@@ -1,6 +1,6 @@
 # server.proxy
 
-- **Type:** `Record<string, string> | Record<string, ProxyDetail>`
+- **Type:** `Record<string, string> | Record<string, ProxyOptions> | ProxyOptions[] | ProxyOptions`
 - **Default:** `undefined`
 
 Configure proxy rules for the dev server or preview server to proxy requests to the specified service.
@@ -75,16 +75,16 @@ export default {
 
 ## Options
 
-The Rsbuild Server Proxy makes use of the [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/2.x) package. Check out its documentation for more advanced usages.
+The Rsbuild server proxy makes use of the [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/2.x) package. Check out its documentation for more advanced usages.
 
-The full type definition of Rsbuild Server Proxy is:
+The full type definition of Rsbuild server proxy is:
 
 ```ts
 import type { Options as HttpProxyOptions } from 'http-proxy-middleware';
 
 type Filter = string | string[] | ((pathname: string, req: Request) => boolean);
 
-type ProxyDetail = HttpProxyOptions & {
+type ProxyOptions = HttpProxyOptions & {
   bypass?: (
     req: IncomingMessage,
     res: ServerResponse,
@@ -93,14 +93,14 @@ type ProxyDetail = HttpProxyOptions & {
   context?: Filter;
 };
 
-type ProxyOptions =
+type ProxyConfig =
+  | ProxyOptions
+  | ProxyOptions[]
   | Record<string, string>
-  | Record<string, ProxyDetail>
-  | ProxyDetail[]
-  | ProxyDetail;
+  | Record<string, ProxyOptions>;
 ```
 
-In addition to the http-proxy-middleware option, Rsbuild also support the bypass and context configuration.
+In addition to the `http-proxy-middleware` option, Rsbuild also support the `bypass` and `context` options.
 
 ### bypass
 
@@ -132,10 +132,9 @@ export default {
 
 ### context
 
-If you want to proxy multiple, specific paths to the same target, you can use an array of one or more objects with a context property.
+Used to proxy multiple specified paths to the same target.
 
 ```js
-// proxy multiple
 export default {
   server: {
     proxy: [

website/docs/zh/config/server/proxy.mdx

@@ -1,6 +1,6 @@
 # server.proxy
 
-- **类型：** `Record<string, string> | Record<string, ProxyDetail>`
+- **类型：** `Record<string, string> | Record<string, ProxyOptions> | ProxyOptions[] | ProxyOptions`
 - **默认值：** `undefined`
 
 为开发服务器或预览服务器配置代理规则，将请求代理到指定的服务上。
@@ -75,16 +75,16 @@ export default {
 
 ## 选项
 
-Rsbuild Server Proxy 基于 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/2.x) 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+Rsbuild server proxy 基于 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/2.x) 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
 
-Rsbuild Server Proxy 完整类型定义为：
+Rsbuild server proxy 完整类型定义为：
 
 ```ts
 import type { Options as HttpProxyOptions } from 'http-proxy-middleware';
 
 type Filter = string | string[] | ((pathname: string, req: Request) => boolean);
 
-type ProxyDetail = HttpProxyOptions & {
+type ProxyOptions = HttpProxyOptions & {
   bypass?: (
     req: IncomingMessage,
     res: ServerResponse,
@@ -93,14 +93,14 @@ type ProxyDetail = HttpProxyOptions & {
   context?: Filter;
 };
 
-type ProxyOptions =
+type ProxyConfig =
+  | ProxyOptions
+  | ProxyOptions[]
   | Record<string, string>
-  | Record<string, ProxyDetail>
-  | ProxyDetail[]
-  | ProxyDetail;
+  | Record<string, ProxyOptions>;
 ```
 
-除了 http-proxy-middleware 的选项外，Rsbuild 还支持 bypass 和 context 两个配置项。
+除了 `http-proxy-middleware` 的选项外，Rsbuild 还支持 `bypass` 和 `context` 两个选项。
 
 ### bypass
 
@@ -132,10 +132,9 @@ export default {
 
 ### context
 
-如果你想代理多个特定的路径到同一个目标，可以使用 context 配置项。
+用于代理多个指定的路径到同一个目标。
 
 ```js
-// 代理多个路径到同一个目标
 export default {
   server: {
     proxy: [