feat: advanced esm

Author: JSerFeng

examples/express-plugin/rslib.config.ts

@@ -8,6 +8,9 @@ export default defineConfig({
       output: {
         distPath: './dist/esm',
       },
+      experiments: {
+        advancedEsm: true,
+      },
     },
     {
       format: 'cjs',

examples/react-component-bundle/rslib.config.ts

@@ -7,6 +7,9 @@ export default defineConfig({
     {
       format: 'esm',
       dts: true,
+      experiments: {
+        advancedEsm: true,
+      },
       output: {
         distPath: './dist/esm',
       },

examples/solid-component-bundle/rslib.config.ts

@@ -8,6 +8,9 @@ export default defineConfig({
     {
       format: 'esm',
       dts: true,
+      experiments: {
+        advancedEsm: true,
+      },
     },
   ],
   output: {

examples/vue-component-bundle/rslib.config.ts

@@ -3,7 +3,14 @@ import { pluginUnpluginVue } from 'rsbuild-plugin-unplugin-vue';
 
 export default defineConfig({
   plugins: [pluginUnpluginVue()],
-  lib: [{ format: 'esm' }],
+  lib: [
+    {
+      format: 'esm',
+      experiments: {
+        advancedEsm: true,
+      },
+    },
+  ],
   output: {
     target: 'web',
   },

packages/core/src/config.ts

@@ -596,11 +596,13 @@ const composeFormatConfig = ({
   bundle = true,
   umdName,
   pkgJson,
+  advancedEsm,
 }: {
   format: Format;
   pkgJson: PkgJson;
   bundle?: boolean;
   umdName?: Rspack.LibraryName;
+  advancedEsm: boolean;
 }): EnvironmentConfig => {
   const jsParserOptions: Record<string, Rspack.JavascriptParserOptions> = {
     cjs: {
@@ -620,13 +622,17 @@ const composeFormatConfig = ({
     },
   };
 
+  const experimentalEsmOutput = bundle && format === 'esm' && advancedEsm;
+
   // The built-in Rslib plugin will apply to all formats except the `mf` format.
   // The `mf` format functions more like an application than a library and requires additional webpack runtime.
   const plugins = [
     new rspack.experiments.RslibPlugin({
       interceptApiPlugin: true,
+      forceNodeShims: true,
     }),
-  ];
+    experimentalEsmOutput && new rspack.experiments.EsmLibraryPlugin(),
+  ].filter(Boolean);
 
   switch (format) {
     case 'esm':
@@ -643,8 +649,10 @@ const composeFormatConfig = ({
               },
             },
             optimization: {
-              concatenateModules: true,
+              // experimentalEsmOutput don't need concatenateModules
+              concatenateModules: !experimentalEsmOutput,
               sideEffects: 'flag',
+              runtimeChunk: experimentalEsmOutput ? 'single' : undefined,
               avoidEntryIife: true,
               splitChunks: {
                 // Splitted "sync" chunks will make entry modules can't be inlined.
@@ -653,10 +661,12 @@ const composeFormatConfig = ({
             },
             output: {
               module: true,
-              chunkFormat: 'module',
-              library: {
-                type: 'modern-module',
-              },
+              chunkFormat: experimentalEsmOutput ? false : 'module',
+              library: experimentalEsmOutput
+                ? undefined
+                : {
+                    type: 'modern-module',
+                  },
               chunkLoading: 'import',
               workerChunkLoading: 'import',
             },
@@ -1719,7 +1729,9 @@ async function composeLibRsbuildConfig(
     externalHelpers = false,
     redirect = {},
     umdName,
+    experiments,
   } = config;
+  const advancedEsm = experiments?.advancedEsm;
   const { rsbuildConfig: bundleConfig } = composeBundleConfig(bundle);
   const { rsbuildConfig: shimsConfig, enabledShims } = composeShimsConfig(
     format,
@@ -1730,6 +1742,7 @@ async function composeLibRsbuildConfig(
     pkgJson: pkgJson!,
     bundle,
     umdName,
+    advancedEsm: advancedEsm ?? false,
   });
   const externalHelpersConfig = composeExternalHelpersConfig(
     externalHelpers,
@@ -1929,6 +1942,7 @@ export async function composeCreateRsbuildConfig(
           shims: true,
           umdName: true,
           outBase: true,
+          experiments: true,
         }),
       ),
     };

packages/core/src/types/config.ts

@@ -241,6 +241,15 @@ export type Redirect = {
   dts?: DtsRedirect;
 };
 
+export type LibExperiments = {
+  /**
+   * Whether to enable Rspack advanced ESM output.
+   * @defaultValue `false`
+   * @see {@link https://rslib.rs/config/lib/experiments#experimentsadvancedesm}
+   */
+  advancedEsm?: boolean;
+};
+
 export interface LibConfig extends EnvironmentConfig {
   /**
    * The unique identifier of the library.
@@ -343,6 +352,12 @@ export interface LibConfig extends EnvironmentConfig {
    * @inheritdoc
    */
   output?: RslibOutputConfig;
+  /**
+   * Options for experimental features.
+   * @defaultValue `{}`
+   * @see {@link https://rslib.rs/config/lib/experiments}
+   */
+  experiments?: LibExperiments;
 }
 
 export type LibOnlyConfig = Omit<LibConfig, keyof EnvironmentConfig>;

packages/core/tests/__snapshots__/config.test.ts.snap

@@ -951,6 +951,7 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
     nodeEnv: false,
     concatenateModules: true,
     sideEffects: 'flag',
+    runtimeChunk: undefined,
     avoidEntryIife: true
   },
   plugins: [
@@ -975,7 +976,8 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
       name: 'RslibPlugin',
       _args: [
         {
-          interceptApiPlugin: true
+          interceptApiPlugin: true,
+          forceNodeShims: true
         }
       ]
     },
@@ -1673,7 +1675,8 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
       name: 'RslibPlugin',
       _args: [
         {
-          interceptApiPlugin: true
+          interceptApiPlugin: true,
+          forceNodeShims: true
         }
       ]
     },
@@ -2276,7 +2279,8 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
       name: 'RslibPlugin',
       _args: [
         {
-          interceptApiPlugin: true
+          interceptApiPlugin: true,
+          forceNodeShims: true
         }
       ]
     },
@@ -2878,7 +2882,8 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
       name: 'RslibPlugin',
       _args: [
         {
-          interceptApiPlugin: true
+          interceptApiPlugin: true,
+          forceNodeShims: true
         }
       ]
     },
@@ -3020,7 +3025,7 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
         use: [
           /* config.module.rule('css').use('mini-css-extract') */
           {
-            loader: '<ROOT>/node_modules/<PNPM_INNER>/@rspack/core/dist/cssExtractLoader.js'
+            loader: '/Users/bytedance/libs/rspack-esm-lib-plugin/packages/rspack/dist/cssExtractLoader.js'
           },
           /* config.module.rule('css').use('css') */
           {
@@ -3690,6 +3695,7 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
             "optimization": {
               "avoidEntryIife": true,
               "concatenateModules": true,
+              "runtimeChunk": undefined,
               "sideEffects": "flag",
               "splitChunks": {
                 "chunks": "async",
@@ -3708,6 +3714,7 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
               RslibPlugin {
                 "_args": [
                   {
+                    "forceNodeShims": true,
                     "interceptApiPlugin": true,
                   },
                 ],
@@ -3990,6 +3997,7 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
               RslibPlugin {
                 "_args": [
                   {
+                    "forceNodeShims": true,
                     "interceptApiPlugin": true,
                   },
                 ],
@@ -4233,6 +4241,7 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
               RslibPlugin {
                 "_args": [
                   {
+                    "forceNodeShims": true,
                     "interceptApiPlugin": true,
                   },
                 ],
@@ -4475,6 +4484,7 @@ exports[`Should compose create Rsbuild config correctly > Merge Rsbuild config i
               RslibPlugin {
                 "_args": [
                   {
+                    "forceNodeShims": true,
                     "interceptApiPlugin": true,
                   },
                 ],