@rsbuild/core 1.2.7 → 1.2.9

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.9",
   "description": "The Rspack-based build tool.",
   "homepage": "https://rsbuild.dev",
   "bugs": {
@@ -54,7 +54,7 @@
   "devDependencies": {
     "@rslib/core": "0.4.1",
     "@types/connect": "3.4.38",
-    "@types/node": "^22.13.1",
+    "@types/node": "^22.13.4",
     "@types/on-finished": "2.3.4",
     "@types/webpack-bundle-analyzer": "4.7.0",
     "@types/ws": "^8.5.14",
@@ -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"