feat: expose server.printUrls method (#3260)

Author: chenjiahan

packages/core/src/server/devServer.ts

@@ -37,6 +37,7 @@ type HTTPServer = Server | Http2SecureServer;
 export type RsbuildDevServer = {
   /**
    * Listen the Rsbuild server.
+   * Do not call this method if you are using a custom server.
    */
   listen: () => Promise<{
     port: number;
@@ -45,14 +46,10 @@ export type RsbuildDevServer = {
       close: () => Promise<void>;
     };
   }>;
-
-  /** The following APIs can be used when using a custom server */
-
   /**
-   * The Rsbuild server environment API
+   * Environment API of Rsbuild server.
    */
   environments: EnvironmentAPI;
-
   /**
    * The resolved port.
    * By default, Rsbuild server listens on port `3000` and automatically increments the port number if the port is occupied.
@@ -70,13 +67,17 @@ export type RsbuildDevServer = {
   afterListen: () => Promise<void>;
   /**
    * Activate socket connection.
-   * This is used if you are using a custom server.
+   * This ensures that HMR works properly.
    */
   connectWebSocket: (options: { server: HTTPServer }) => void;
   /**
    * Close the Rsbuild server.
    */
   close: () => Promise<void>;
+  /**
+   * Print the server URLs.
+   */
+  printUrls: () => void;
 };
 
 const formatDevConfig = (config: NormalizedDevConfig, port: number) => {
@@ -182,25 +183,21 @@ export async function createDevServer<
     environments: options.context.environments,
   });
 
-  if (runCompile) {
-    options.context.hooks.onBeforeCreateCompiler.tap(() => {
-      // print server url should between listen and beforeCompile
-      printServerURLs({
-        urls,
-        port,
-        routes,
-        protocol,
-        printUrls: config.server.printUrls,
-      });
-    });
-  } else {
+  const printUrls = () => {
     printServerURLs({
       urls,
       port,
       routes,
       protocol,
       printUrls: config.server.printUrls,
     });
+  };
+
+  if (runCompile) {
+    // print server url should between listen and beforeCompile
+    options.context.hooks.onBeforeCreateCompiler.tap(printUrls);
+  } else {
+    printUrls();
   }
 
   const compileMiddlewareAPI = runCompile ? await startCompile() : undefined;
@@ -339,6 +336,7 @@ export async function createDevServer<
       await devMiddlewares.close();
       await fileWatcher?.close();
     },
+    printUrls,
   };
 
   logger.debug('create dev server done');

website/docs/en/api/javascript-api/instance.mdx

@@ -242,7 +242,7 @@ await rsbuild.startDevServer({
 
 Rsbuild comes with a built-in dev server designed to improve the development experience. When you run the `rsbuild dev` command, the server will start, providing features such as page preview, routing, and hot module reloading.
 
-If you want to integrate Rsbuild dev server into an custom server, you can use this method to get the instance methods of Rsbuild dev server and call them on demand.
+If you want to integrate Rsbuild dev server into an custom server, you can use this method to get the instance methods of dev server and call them on demand.
 
 - **Type:**
 
@@ -253,15 +253,13 @@ type EnvironmentAPI = {
      * Get stats info about current environment.
      */
     getStats: () => Promise<Stats>;
-
     /**
      * Load and execute stats bundle in server.
      *
      * @param entryName - relate to Rsbuild's `source.entry`
      * @returns the return value of entry module.
      */
     loadBundle: <T = unknown>(entryName: string) => Promise<T>;
-
     /**
      * Get the compiled HTML template.
      */
@@ -270,39 +268,49 @@ type EnvironmentAPI = {
 };
 
 type RsbuildDevServer = {
-  /** start the Rsbuild DevServer */
+  /**
+   * Listen the Rsbuild server.
+   * Do not call this method if you are using a custom server.
+   */
   listen: () => Promise<{
-    urls: string[];
     port: number;
-    server: Server;
+    urls: string[];
+    server: {
+      close: () => Promise<void>;
+    };
   }>;
-
-  /** The following APIs will be used when you use a custom server */
-
-  /** The Rsbuild server environment API */
+  /**
+   * Environment API of Rsbuild server.
+   */
   environments: EnvironmentAPI;
-
   /**
-   * The resolved port
-   *
-   * By default, Rsbuild Server listens on port `3000` and automatically increments the port number when the port is occupied.
+   * The resolved port.
+   * By default, Rsbuild server listens on port `3000` and automatically increments the port number if the port is occupied.
    */
   port: number;
-
   /**
-   * connect app instance.
-   *
+   * The `connect` app instance.
    * Can be used to attach custom middlewares to the dev server.
    */
-  middlewares: Middlewares;
-
-  /** Notify Rsbuild that the custom server has started */
+  middlewares: Connect.Server;
+  /**
+   * Notify that the Rsbuild server has been started.
+   * Rsbuild will trigger `onAfterStartDevServer` hook in this stage.
+   */
   afterListen: () => Promise<void>;
-
+  /**
+   * Activate socket connection.
+   * This ensures that HMR works properly.
+   */
   connectWebSocket: (options: { server: HTTPServer }) => void;
-
-  /** close the Rsbuild DevServer */
+  /**
+   * Close the Rsbuild server.
+   */
   close: () => Promise<void>;
+  /**
+   * Print the server URLs.
+   */
+  printUrls: () => void;
 };
 
 type CreateDevServerOptions = {

website/docs/zh/api/javascript-api/instance.mdx

@@ -264,7 +264,7 @@ await rsbuild.startDevServer({
 
 Rsbuild 配备了一个内置的开发服务器，当你执行 `rsbuild dev` 时，将启动 Rsbuild dev server，并提供页面预览、路由、模块热更新等功能。
 
-如果你希望将 Rsbuild dev server 集成到自定义的 server 中，可以通过该方法获取 Rsbuild dev server 的实例方法，进行按需调用。
+如果你希望将 Rsbuild dev server 集成到自定义的 server 中，可以通过该方法获取 dev server 的实例方法，按需进行调用。
 
 - **类型：**
 
@@ -275,15 +275,13 @@ type EnvironmentAPI = {
      * 获取当前环境的构建信息
      */
     getStats: () => Promise<Stats>;
-
     /**
      * 在服务端加载并执行构建产物
      *
      * @param entryName - 入口名称，和 Rsbuild source.entry 的某一个 key 值对应
      * @returns 入口模块的返回值
      */
     loadBundle: <T = unknown>(entryName: string) => Promise<T>;
-
     /**
      * 获取编译后的 HTML 模版内容
      */
@@ -292,31 +290,49 @@ type EnvironmentAPI = {
 };
 
 type RsbuildDevServer = {
-  /** 启动 Rsbuild DevServer */
+  /**
+   * 监听 Rsbuild server
+   * 当你使用自定义 server 时，不需要调用该方法
+   */
   listen: () => Promise<{
-    urls: string[];
     port: number;
-    server: Server;
+    urls: string[];
+    server: {
+      close: () => Promise<void>;
+    };
   }>;
-
-  /** 以下 API 在使用自定义 Server 时会用到 */
-
-  /** Rsbuild server environment API */
+  /**
+   * Rsbuild server 提供的 environment API
+   */
   environments: EnvironmentAPI;
-
-  /** 解析后的端口号 (默认情况下，Rsbuild Server 会监听 `3000` 端口，并在端口被占用时自动递增端口号。) */
+  /**
+   * 解析后的端口号
+   * 默认情况下，Rsbuild Server 会监听 `3000` 端口，如果端口被占用，则自动递增端口号
+   */
   port: number;
-
-  /** Connect 实例，包含 Rsbuild 内置中间件 */
-  middlewares: Middlewares;
-
-  /** 通知 Rsbuild 自定义 Server 已启动 */
+  /**
+   * `connect` 实例
+   * 可用于向 dev server 附加自定义中间件
+   */
+  middlewares: Connect.Server;
+  /**
+   * 通知 Rsbuild 自定义 Server 已启动
+   * Rsbuild 会在此阶段触发 `onAfterStartDevServer` 钩子
+   */
   afterListen: () => Promise<void>;
-
+  /**
+   * 激活 socket 连接
+   * 这确保了 HMR 正常工作
+   */
   connectWebSocket: (options: { server: HTTPServer }) => void;
-
-  /** 关闭 Rsbuild DevServer */
+  /**
+   * 关闭 Rsbuild server
+   */
   close: () => Promise<void>;
+  /**
+   * 打印 server URLs
+   */
+  printUrls: () => void;
 };
 
 type CreateDevServerOptions = {