@rsbuild/core 1.2.7 → 1.2.8

package/dist-types/types/plugin.d.ts

@@ -4,7 +4,7 @@ import type { ChainIdentifier } from '../configChain';
 import type { ModifyRspackConfigUtils, NormalizedConfig, NormalizedEnvironmentConfig, RsbuildConfig } from './config';
 import type { RsbuildContext } from './context';
 import type { EnvironmentContext, ModifyBundlerChainFn, ModifyChainUtils, ModifyEnvironmentConfigFn, ModifyHTMLTagsFn, ModifyRsbuildConfigFn, OnAfterBuildFn, OnAfterCreateCompilerFn, OnAfterEnvironmentCompileFn, OnAfterStartDevServerFn, OnAfterStartProdServerFn, OnBeforeBuildFn, OnBeforeCreateCompilerFn, OnBeforeEnvironmentCompileFn, OnBeforeStartDevServerFn, OnBeforeStartProdServerFn, OnCloseBuildFn, OnCloseDevServerFn, OnDevCompileDoneFn, OnExitFn } from './hooks';
-import type { RsbuildTarget } from './rsbuild';
+import type { RsbuildInstance, RsbuildTarget } from './rsbuild';
 import type { Rspack } from './rspack';
 import type { HtmlRspackPlugin } from './thirdParty';
 import type { Falsy } from './utils';
@@ -63,42 +63,7 @@ export type PluginMeta = {
     environment: string;
     instance: RsbuildPlugin;
 };
-export type PluginManager = {
-    getPlugins: (options?: {
-        /**
-         * Get the plugins in the specified environment.
-         *
-         * If environment is not specified, get the global plugins.
-         */
-        environment: string;
-    }) => RsbuildPlugin[];
-    addPlugins: (plugins: Array<RsbuildPlugin | Falsy>, options?: {
-        /**
-         * Insert before the specified plugin.
-         */
-        before?: string;
-        /**
-         * Add a plugin for the specified environment.
-         * If environment is not specified, it will be registered as a global plugin (effective in all environments)
-         */
-        environment?: string;
-    }) => void;
-    removePlugins: (pluginNames: string[], options?: {
-        /**
-         * Remove the plugin in the specified environment.
-         *
-         * If environment is not specified, remove it in all environments.
-         */
-        environment: string;
-    }) => void;
-    isPluginExists: (pluginName: string, options?: {
-        /**
-         * Whether it exists in the specified environment.
-         *
-         * If environment is not specified, determine whether the plugin is a global plugin.
-         */
-        environment: string;
-    }) => boolean;
+export type PluginManager = Pick<RsbuildInstance, 'getPlugins' | 'addPlugins' | 'isPluginExists' | 'removePlugins'> & {
     /** Get all plugins with environment info */
     getAllPluginsWithMeta: () => PluginMeta[];
 };
@@ -300,50 +265,157 @@ declare function getNormalizedConfig(options: {
  * Define a generic Rsbuild plugin API that provider can extend as needed.
  */
 export type RsbuildPluginAPI = Readonly<{
+    /**
+     * A read-only object that provides some context information.
+     */
     context: Readonly<RsbuildContext>;
-    isPluginExists: PluginManager['isPluginExists'];
-    onExit: PluginHook<OnExitFn>;
-    onCloseBuild: PluginHook<OnCloseBuildFn>;
+    /**
+     * Explicitly expose some properties or methods of the current plugin,
+     * and other plugins can get these APIs through `api.useExposed`.
+     */
+    expose: <T = any>(id: string | symbol, api: T) => void;
+    /**
+     * Get the Rsbuild config, this method must be called after the
+     * `modifyRsbuildConfig` hook is executed.
+     */
+    getRsbuildConfig: GetRsbuildConfig;
+    /**
+     * Get the all normalized Rsbuild config or the Rsbuild config of a specified
+     * environment, this method must be called after the
+     * `modifyRsbuildConfig` hook is executed.
+     */
+    getNormalizedConfig: typeof getNormalizedConfig;
+    /**
+     * Determines if a plugin has been registered in the current Rsbuild instance.
+     */
+    isPluginExists: (pluginName: string, options?: {
+        /**
+         * Whether it exists in the specified environment.
+         * If environment is not specified, determine whether the plugin is a global plugin.
+         */
+        environment: string;
+    }) => boolean;
+    /**
+     * Allows you to modify the Rspack configuration using the `rspack-chain` API,
+     * providing the same functionality as `tools.bundlerChain`.
+     */
+    modifyBundlerChain: PluginHook<ModifyBundlerChainFn>;
+    /**
+     * Modify the Rsbuild configuration of a specific environment.
+     */
+    modifyEnvironmentConfig: PluginHook<ModifyEnvironmentConfigFn>;
+    /**
+     * Modify the tags that are injected into the HTML.
+     */
+    modifyHTMLTags: PluginHook<ModifyHTMLTagsFn>;
+    /**
+     * To modify the Rspack config, you can directly modify the config object,
+     * or return a new object to replace the previous object.
+     */
+    modifyRspackConfig: PluginHook<ModifyRspackConfigFn>;
+    /**
+     * Modify the config passed to the Rsbuild, you can directly modify the config object,
+     * or return a new object to replace the previous object.
+     */
+    modifyRsbuildConfig: PluginHook<ModifyRsbuildConfigFn>;
+    /**
+     * Allows you to modify the webpack configuration using the `rspack-chain` API,
+     * providing the same functionality as `tools.bundlerChain`.
+     */
+    modifyWebpackChain: PluginHook<ModifyWebpackChainFn>;
+    /**
+     * To modify the webpack config, you can directly modify the config object,
+     * or return a new object to replace the previous object.
+     */
+    modifyWebpackConfig: PluginHook<ModifyWebpackConfigFn>;
+    /**
+     * A callback function that is triggered after running the production build.
+     * You can access the build result information via the
+     * [stats](https://rspack.dev/api/javascript-api/stats) parameter.
+     */
     onAfterBuild: PluginHook<OnAfterBuildFn>;
-    onBeforeBuild: PluginHook<OnBeforeBuildFn>;
+    /**
+     * A callback function that is triggered after the compiler instance has been
+     * created, but before the build process. This hook is called when you run
+     * `rsbuild.startDevServer`, `rsbuild.build`, or `rsbuild.createCompiler`.
+     */
+    onAfterCreateCompiler: PluginHook<OnAfterCreateCompilerFn>;
+    /**
+     * A callback function that is triggered after the compilation of a single environment.
+     * You can access the build result information via the
+     * [stats](https://rspack.dev/api/javascript-api/stats) parameter.
+     */
     onAfterEnvironmentCompile: PluginHook<OnAfterEnvironmentCompileFn>;
-    onBeforeEnvironmentCompile: PluginHook<OnBeforeEnvironmentCompileFn>;
-    onCloseDevServer: PluginHook<OnCloseDevServerFn>;
-    onDevCompileDone: PluginHook<OnDevCompileDoneFn>;
+    /**
+     * Called after starting the dev server, you can get the port number with the
+     * `port` parameter, and the page routes info with the `routes` parameter.
+     */
     onAfterStartDevServer: PluginHook<OnAfterStartDevServerFn>;
-    onBeforeStartDevServer: PluginHook<OnBeforeStartDevServerFn>;
+    /**
+     * Called after starting the production preview server, you can get the port
+     * number with the `port` parameter, and the page routes info with the
+     * `routes` parameter.
+     */
     onAfterStartProdServer: PluginHook<OnAfterStartProdServerFn>;
-    onBeforeStartProdServer: PluginHook<OnBeforeStartProdServerFn>;
-    onAfterCreateCompiler: PluginHook<OnAfterCreateCompilerFn>;
+    /**
+     * A callback function that is triggered before the production build is executed.
+     */
+    onBeforeBuild: PluginHook<OnBeforeBuildFn>;
+    /**
+     * A callback function that is triggered after the Compiler instance has been
+     * created, but before the build process begins. This hook is called when you
+     * run `rsbuild.startDevServer`, `rsbuild.build`, or `rsbuild.createCompiler`.
+     */
     onBeforeCreateCompiler: PluginHook<OnBeforeCreateCompilerFn>;
-    modifyHTMLTags: PluginHook<ModifyHTMLTagsFn>;
-    modifyRsbuildConfig: PluginHook<ModifyRsbuildConfigFn>;
-    modifyEnvironmentConfig: PluginHook<ModifyEnvironmentConfigFn>;
-    modifyBundlerChain: PluginHook<ModifyBundlerChainFn>;
-    /** Only works when bundler is Rspack */
-    modifyRspackConfig: PluginHook<ModifyRspackConfigFn>;
-    /** Only works when bundler is webpack */
-    modifyWebpackChain: PluginHook<ModifyWebpackChainFn>;
-    /** Only works when bundler is webpack */
-    modifyWebpackConfig: PluginHook<ModifyWebpackConfigFn>;
-    getRsbuildConfig: GetRsbuildConfig;
-    getNormalizedConfig: typeof getNormalizedConfig;
     /**
-     * For plugin communication
+     * A callback function that is triggered before the compilation of a single environment.
      */
-    expose: <T = any>(id: string | symbol, api: T) => void;
-    useExposed: <T = any>(id: string | symbol) => T | undefined;
+    onBeforeEnvironmentCompile: PluginHook<OnBeforeEnvironmentCompileFn>;
     /**
-     * Used to transform the code of modules.
+     * Called before starting the dev server.
      */
-    transform: TransformFn;
+    onBeforeStartDevServer: PluginHook<OnBeforeStartDevServerFn>;
+    /**
+     * Called before starting the production preview server.
+     */
+    onBeforeStartProdServer: PluginHook<OnBeforeStartProdServerFn>;
+    /**
+     * Called when closing the build instance. Can be used to perform cleanup
+     * operations when the building is closed.
+     */
+    onCloseBuild: PluginHook<OnCloseBuildFn>;
+    /**
+     * Called when closing the dev server. Can be used to perform cleanup
+     * operations when the dev server is closed.
+     */
+    onCloseDevServer: PluginHook<OnCloseDevServerFn>;
+    /**
+     * Called after each development mode build, you can use `isFirstCompile`
+     * to determine whether it is the first build.
+     */
+    onDevCompileDone: PluginHook<OnDevCompileDoneFn>;
+    /**
+     * Called when the process is going to exit, this hook can only execute
+     * synchronous code.
+     */
+    onExit: PluginHook<OnExitFn>;
     /**
-     * Process all the asset generated by Rspack.
+     * Modify assets before emitting, the same as Rspack's
+     * [compilation.hooks.processAssets](https://rspack.dev/api/plugin-api/compilation-hooks#processassets) hook.
      */
     processAssets: ProcessAssetsFn;
     /**
-     * Defines a custom resolver. A resolver can be useful for e.g. locating third-party dependencies.
+     * Intercept and modify module request information before module resolution begins.
+     * The same as Rspack's [normalModuleFactory.hooks.resolve](https://rspack.dev/api/plugin-api/normal-module-factory-hooks#resolve) hook.
      */
     resolve: ResolveFn;
+    /**
+     * Used to transform the code of modules.
+     */
+    transform: TransformFn;
+    /**
+     * Get the properties or methods exposed by other plugins.
+     */
+    useExposed: <T = any>(id: string | symbol) => T | undefined;
 }>;
 export {};

package/dist-types/types/rsbuild.d.ts

@@ -4,10 +4,11 @@ import type { RsbuildDevServer } from '../server/devServer';
 import type { StartServerResult } from '../server/helper';
 import type { RsbuildConfig } from './config';
 import type { NormalizedConfig, NormalizedEnvironmentConfig } from './config';
-import type { InternalContext, RsbuildContext } from './context';
-import type { PluginManager, RsbuildPluginAPI } from './plugin';
+import type { InternalContext } from './context';
+import type { PluginManager, RsbuildPlugin, RsbuildPluginAPI } from './plugin';
 import type { Rspack } from './rspack';
 import type { WebpackConfig } from './thirdParty';
+import type { Falsy } from './utils';
 export type Bundler = 'rspack' | 'webpack';
 export type StartDevServerOptions = {
     /**
@@ -23,7 +24,6 @@ export type StartDevServerOptions = {
 export type CreateDevServerOptions = StartDevServerOptions & {
     /**
      * Whether to trigger Rsbuild compilation
-     *
      * @default true
      */
     runCompile?: boolean;
@@ -118,33 +118,100 @@ export type RsbuildProvider<B extends 'rspack' | 'webpack' = 'rspack'> = (option
     helpers: RsbuildProviderHelpers;
 }) => Promise<ProviderInstance<B>>;
 export type RsbuildInstance = {
-    context: RsbuildContext;
-    addPlugins: PluginManager['addPlugins'];
-    getPlugins: PluginManager['getPlugins'];
-    removePlugins: PluginManager['removePlugins'];
-    isPluginExists: PluginManager['isPluginExists'];
-    build: ProviderInstance['build'];
+    /**
+     * Register one or more Rsbuild plugins, which can be called multiple times.
+     * This method needs to be called before compiling. If it is called after
+     * compiling, it will not affect the compilation result.
+     */
+    addPlugins: (plugins: Array<RsbuildPlugin | Falsy>, options?: {
+        /**
+         * Insert before the specified plugin.
+         */
+        before?: string;
+        /**
+         * Add a plugin for the specified environment.
+         * If environment is not specified, it will be registered as a global plugin (effective in all environments)
+         */
+        environment?: string;
+    }) => void;
+    /**
+     * Get all the Rsbuild plugins registered in the current Rsbuild instance.
+     */
+    getPlugins: (options?: {
+        /**
+         * Get the plugins in the specified environment.
+         * If environment is not specified, get the global plugins.
+         */
+        environment: string;
+    }) => RsbuildPlugin[];
+    /**
+     * Removes one or more Rsbuild plugins, which can be called multiple times.
+     * This method needs to be called before compiling. If it is called after
+     * compiling, it will not affect the compilation result.
+     */
+    removePlugins: (pluginNames: string[], options?: {
+        /**
+         * Remove the plugin in the specified environment.
+         * If environment is not specified, remove it in all environments.
+         */
+        environment: string;
+    }) => void;
+    /**
+     * Perform a production mode build. This method will generate optimized
+     * production bundles and emit them to the output directory.
+     */
+    build: Build;
+    /**
+     * Start a server to preview the production build locally.
+     * This method should be executed after `rsbuild.build`.
+     */
     preview: (options?: PreviewOptions) => Promise<StartServerResult>;
-    initConfigs: ProviderInstance['initConfigs'];
-    inspectConfig: ProviderInstance['inspectConfig'];
-    createCompiler: ProviderInstance['createCompiler'];
-    createDevServer: ProviderInstance['createDevServer'];
-    startDevServer: ProviderInstance['startDevServer'];
-    getRsbuildConfig: RsbuildPluginAPI['getRsbuildConfig'];
-    getNormalizedConfig: RsbuildPluginAPI['getNormalizedConfig'];
-    onBeforeBuild: RsbuildPluginAPI['onBeforeBuild'];
-    onBeforeCreateCompiler: RsbuildPluginAPI['onBeforeCreateCompiler'];
-    onBeforeStartDevServer: RsbuildPluginAPI['onBeforeStartDevServer'];
-    onBeforeStartProdServer: RsbuildPluginAPI['onBeforeStartProdServer'];
-    onAfterBuild: RsbuildPluginAPI['onAfterBuild'];
-    onAfterCreateCompiler: RsbuildPluginAPI['onAfterCreateCompiler'];
-    onAfterStartDevServer: RsbuildPluginAPI['onAfterStartDevServer'];
-    onAfterStartProdServer: RsbuildPluginAPI['onAfterStartProdServer'];
-    onCloseDevServer: RsbuildPluginAPI['onCloseDevServer'];
-    onDevCompileDone: RsbuildPluginAPI['onDevCompileDone'];
-    onExit: RsbuildPluginAPI['onExit'];
-    onCloseBuild: RsbuildPluginAPI['onCloseBuild'];
-};
+    /**
+     * Initialize and return the internal Rspack configurations used by Rsbuild.
+     * This method processes all plugins and configurations to generate the final
+     * Rspack configs. Note: You typically don't need to call this method directly
+     * since it's automatically invoked by methods like `rsbuild.build` and
+     * `rsbuild.startDevServer`.
+     */
+    initConfigs: () => Promise<Rspack.Configuration[]>;
+    /**
+     * Inspect and debug Rsbuild's internal configurations. It provides access to:
+     * - The resolved Rsbuild configuration
+     * - The environment-specific Rsbuild configurations
+     * - The generated Rspack configurations
+     *
+     * The method serializes these configurations to strings and optionally writes
+     * them to disk for inspection.
+     */
+    inspectConfig: (options?: InspectConfigOptions) => Promise<InspectConfigResult>;
+    /**
+     * Create an Rspack [Compiler](https://rspack.dev/api/javascript-api/compiler)
+     * instance. If there are multiple [environments](/config/environments) for
+     * this build, the return value is `MultiCompiler`.
+     */
+    createCompiler: CreateCompiler;
+    /**
+     * Rsbuild includes a built-in dev server designed to improve the development
+     * experience. When you run the `rsbuild dev` command, the server starts
+     * automatically and provides features such as page preview, routing, and hot
+     * module reloading.
+     *
+     * If you want to integrate the Rsbuild dev server into a custom server, you
+     * can use the `createDevServer` method to create a dev server instance and
+     * call its methods as needed.
+     *
+     * If you want to directly start the Rsbuild dev server, use the
+     * `rsbuild.startDevServer` method.
+     */
+    createDevServer: CreateDevServer;
+    /**
+     * Start the local dev server. This method will:
+     *
+     * 1. Start a development server that serves your application.
+     * 2. Watch for file changes and trigger recompilation.
+     */
+    startDevServer: StartDevServer;
+} & Pick<RsbuildPluginAPI, 'context' | 'getNormalizedConfig' | 'getRsbuildConfig' | 'isPluginExists' | 'onAfterBuild' | 'onAfterCreateCompiler' | 'onAfterStartDevServer' | 'onAfterStartProdServer' | 'onBeforeBuild' | 'onBeforeCreateCompiler' | 'onBeforeStartDevServer' | 'onBeforeStartProdServer' | 'onCloseBuild' | 'onCloseDevServer' | 'onDevCompileDone' | 'onExit'>;
 export type RsbuildTarget = 'web' | 'node' | 'web-worker';
 export type RsbuildEntryDescription = Rspack.EntryDescription & {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsbuild/core",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "The Rspack-based build tool.",
   "homepage": "https://rsbuild.dev",
   "bugs": {
@@ -76,7 +76,7 @@
     "on-finished": "2.4.1",
     "open": "^8.4.0",
     "picocolors": "^1.1.1",
-    "postcss": "^8.5.1",
+    "postcss": "^8.5.2",
     "postcss-load-config": "6.0.1",
     "postcss-loader": "8.1.1",
     "prebundle": "1.2.7",
@@ -89,7 +89,7 @@
     "style-loader": "3.3.4",
     "tinyglobby": "^0.2.10",
     "typescript": "^5.7.3",
-    "webpack": "^5.97.1",
+    "webpack": "^5.98.0",
     "webpack-bundle-analyzer": "^4.10.2",
     "webpack-merge": "6.0.1",
     "ws": "^8.18.0"