feat: support outBase config

Author: fi3ework

packages/core/src/config.ts

@@ -889,13 +889,14 @@ const composeEntryConfig = async (
   bundle: LibConfig['bundle'],
   root: string,
   cssModulesAuto: CssLoaderOptionsAuto,
-): Promise<{ entryConfig: EnvironmentConfig; lcp: string | null }> => {
+  userOutBase?: string,
+): Promise<{ entryConfig: EnvironmentConfig; outBase: string | null }> => {
   let entries: RsbuildConfigEntry = rawEntry;
 
   if (!entries) {
     // In bundle mode, return directly to let Rsbuild apply default entry to './src/index.ts'
     if (bundle !== false) {
-      return { entryConfig: {}, lcp: null };
+      return { entryConfig: {}, outBase: null };
     }
 
     // In bundleless mode, set default entry to './src/**'
@@ -957,13 +958,26 @@ const composeEntryConfig = async (
           entry: appendEntryQuery(resolveEntryPath(entries, root)),
         },
       },
-      lcp: null,
+      outBase: null,
     };
   }
 
-  const scanGlobEntries = async (calcLcp: boolean) => {
+  const scanGlobEntries = async (tryResolveOutBase: boolean) => {
     // In bundleless mode, resolve glob patterns and convert them to entry object.
     const resolvedEntries: Record<string, string> = {};
+
+    const resolveOutBase = async (resolvedEntryFiles: string[]) => {
+      // Similar to `rootDir` in tsconfig and `outbase` in esbuild.
+      const lcp = await calcLongestCommonPath(resolvedEntryFiles);
+      // Using the longest common path of all non-declaration input files by default.
+      const outBase = userOutBase
+        ? path.resolve(root, userOutBase)
+        : lcp === null
+          ? root
+          : lcp;
+      return outBase;
+    };
+
     for (const key of Object.keys(entries)) {
       const entry = entries[key];
 
@@ -998,10 +1012,7 @@ const composeEntryConfig = async (
         throw new Error(`Cannot find ${resolvedEntryFiles}`);
       }
 
-      // Similar to `rootDir` in tsconfig and `outbase` in esbuild.
-      const lcp = await calcLongestCommonPath(resolvedEntryFiles);
-      // Using the longest common path of all non-declaration input files by default.
-      const outBase = lcp === null ? root : lcp;
+      const outBase = await resolveOutBase(resolvedEntryFiles);
 
       function getEntryName(file: string) {
         const { dir, name } = path.parse(path.relative(outBase, file));
@@ -1021,7 +1032,7 @@ const composeEntryConfig = async (
         const entryName = getEntryName(file);
 
         if (resolvedEntries[entryName]) {
-          calcLcp &&
+          tryResolveOutBase &&
             logger.warn(
               `Duplicate entry ${color.cyan(entryName)} from ${color.cyan(
                 path.relative(root, file),
@@ -1035,15 +1046,15 @@ const composeEntryConfig = async (
       }
     }
 
-    if (calcLcp) {
-      const lcp = await calcLongestCommonPath(Object.values(resolvedEntries));
-      return { resolvedEntries, lcp };
+    if (tryResolveOutBase) {
+      const outBase = await resolveOutBase(Object.values(resolvedEntries));
+      return { resolvedEntries, outBase };
     }
-    return { resolvedEntries, lcp: null };
+    return { resolvedEntries, outBase: null };
   };
 
-  // LCP could only be determined at the first time of glob scan.
-  const { lcp } = await scanGlobEntries(true);
+  // OutBase could only be determined at the first time of glob scan.
+  const { outBase } = await scanGlobEntries(true);
   const entryConfig: EnvironmentConfig = {
     tools: {
       rspack: {
@@ -1057,7 +1068,7 @@ const composeEntryConfig = async (
 
   return {
     entryConfig,
-    lcp,
+    outBase,
   };
 };
 
@@ -1415,14 +1426,15 @@ async function composeLibRsbuildConfig(
     pkgJson,
     userExternals: config.output?.externals,
   });
-  const { entryConfig, lcp } = await composeEntryConfig(
+  const { entryConfig, outBase } = await composeEntryConfig(
     config.source?.entry!,
     config.bundle,
     rootPath,
     cssModulesAuto,
+    config.outBase,
   );
   const cssConfig = composeCssConfig(
-    lcp,
+    outBase,
     config.bundle,
     banner?.css,
     footer?.css,
@@ -1431,7 +1443,7 @@ async function composeLibRsbuildConfig(
 
   const entryChunkConfig = composeEntryChunkConfig({
     enabledImportMetaUrlShim: enabledShims.cjs['import.meta.url'],
-    contextToWatch: lcp,
+    contextToWatch: outBase,
   });
   const dtsConfig = await composeDtsConfig(config, dtsExtension);
   const externalsWarnConfig = composeExternalsWarnConfig(
@@ -1548,6 +1560,7 @@ export async function composeCreateRsbuildConfig(
           dts: true,
           shims: true,
           umdName: true,
+          outBase: true,
         }),
       ),
     };

packages/core/src/types/config.ts

@@ -285,6 +285,12 @@ export interface LibConfig extends EnvironmentConfig {
    * @see {@link https://lib.rsbuild.dev/config/lib/umd-name}
    */
   umdName?: string;
+  /**
+   * The base directory of the output files.
+   * @defaultValue `undefined`
+   * @see {@link https://lib.rsbuild.dev/config/lib/out-base}
+   */
+  outBase?: string;
 }
 
 export type LibOnlyConfig = Omit<LibConfig, keyof EnvironmentConfig>;

pnpm-lock.yaml

@@ -0,0 +1,6 @@
+{
+  "name": "outbase-custom-entry-dir-test",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module"
+}

tests/integration/outBase/custom-entry/package.json

@@ -0,0 +1,34 @@
+import { defineConfig } from '@rslib/core';
+import { generateBundleEsmConfig } from 'test-helper';
+
+export default defineConfig({
+  lib: [
+    generateBundleEsmConfig({
+      bundle: false,
+      source: {
+        entry: {
+          index: './src/utils/foo',
+        },
+      },
+      output: {
+        distPath: {
+          root: './dist/esm0',
+        },
+      },
+    }),
+    generateBundleEsmConfig({
+      bundle: false,
+      outBase: './src/utils',
+      source: {
+        entry: {
+          index: './src/utils/foo',
+        },
+      },
+      output: {
+        distPath: {
+          root: './dist/esm1',
+        },
+      },
+    }),
+  ],
+});

tests/integration/outBase/custom-entry/rslib.config.ts

@@ -0,0 +1 @@
+export const bar = 'foo';

tests/integration/outBase/custom-entry/src/bar/index.ts

@@ -0,0 +1 @@
+export const foo = 'foo';

tests/integration/outBase/custom-entry/src/utils/foo/index.ts

@@ -0,0 +1,2 @@
+export { foo } from './foo';
+export { bar } from './bar';

tests/integration/outBase/custom-entry/src/utils/index.ts

@@ -0,0 +1,47 @@
+import { join } from 'node:path';
+import { buildAndGetResults } from 'test-helper';
+import { describe, expect, test } from 'vitest';
+
+describe('outBase', async () => {
+  test('base', async () => {
+    const fixturePath = join(__dirname, 'nested-dir');
+    const { files } = await buildAndGetResults({
+      fixturePath,
+    });
+
+    expect(files.esm0!.sort()).toMatchInlineSnapshot(`
+      [
+        "<ROOT>/tests/integration/outBase/nested-dir/dist/esm0/bar/index.js",
+        "<ROOT>/tests/integration/outBase/nested-dir/dist/esm0/foo/index.js",
+        "<ROOT>/tests/integration/outBase/nested-dir/dist/esm0/index.js",
+      ]
+    `);
+
+    expect(files.esm1!.sort()).toMatchInlineSnapshot(`
+      [
+        "<ROOT>/tests/integration/outBase/nested-dir/dist/esm1/utils/bar/index.js",
+        "<ROOT>/tests/integration/outBase/nested-dir/dist/esm1/utils/foo/index.js",
+        "<ROOT>/tests/integration/outBase/nested-dir/dist/esm1/utils/index.js",
+      ]
+    `);
+  });
+
+  test('with custom entry', async () => {
+    const fixturePath = join(__dirname, 'custom-entry');
+    const { files } = await buildAndGetResults({
+      fixturePath,
+    });
+
+    expect(files.esm0!.sort()).toMatchInlineSnapshot(`
+      [
+        "<ROOT>/tests/integration/outBase/custom-entry/dist/esm0/index.js",
+      ]
+    `);
+
+    expect(files.esm1!.sort()).toMatchInlineSnapshot(`
+      [
+        "<ROOT>/tests/integration/outBase/custom-entry/dist/esm1/foo/index.js",
+      ]
+    `);
+  });
+});

tests/integration/outBase/index.test.ts

@@ -0,0 +1,6 @@
+{
+  "name": "outbase-nested-dir-test",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module"
+}

tests/integration/outBase/nested-dir/package.json

@@ -0,0 +1,26 @@
+import { defineConfig } from '@rslib/core';
+import { generateBundleEsmConfig } from 'test-helper';
+
+export default defineConfig({
+  lib: [
+    generateBundleEsmConfig({
+      bundle: false,
+      dts: true,
+      output: {
+        distPath: {
+          root: './dist/esm0',
+        },
+      },
+    }),
+    generateBundleEsmConfig({
+      bundle: false,
+      dts: true,
+      outBase: './src',
+      output: {
+        distPath: {
+          root: './dist/esm1',
+        },
+      },
+    }),
+  ],
+});

tests/integration/outBase/nested-dir/rslib.config.ts

@@ -0,0 +1 @@
+export const bar = 'foo';

tests/integration/outBase/nested-dir/src/utils/bar/index.ts

@@ -0,0 +1 @@
+export const foo = 'foo';

tests/integration/outBase/nested-dir/src/utils/foo/index.ts

@@ -0,0 +1,2 @@
+export { foo } from './foo';
+export { bar } from './bar';

tests/integration/outBase/nested-dir/src/utils/index.ts

@@ -11,5 +11,6 @@
   "dts",
   "shims",
   "id",
-  "umd-name"
+  "umd-name",
+  "out-base"
 ]

website/docs/en/config/lib/_meta.json

@@ -0,0 +1,52 @@
+# lib.outBase
+
+- **Type:** `boolean`
+- **Default Value:** `undefined`
+
+:::info
+
+`outBase` is a specific configuration for [bundleless mode](/guide/basic/output-structure#bundle--bundleless). This configuration does not take effect in bundle mode because all output files are bundled into a single file, so there's no need to determine the base output directory.
+
+:::
+
+When building a bundleless project where source files exist across multiple directories, the output directory structure will be replicated relative to the `outBase` directory in the output directory. If no base output directory is specified, the [lowest common ancestor](https://en.wikipedia.org/wiki/Lowest_common_ancestor) of all input entry points is used by default.
+
+Configuring `outBase` will change the base output directory path. The path of `outBase` is relative to the current process directory.
+
+For example, we have the following directory structure:
+
+```txt
+.
+├── package.json
+├── rslib.config.ts
+└── src
+    └── utils
+        ├── bar
+        │   └── index.ts
+        ├── foo
+        │   └── index.ts
+        └── index.ts
+```
+
+If the output base directory is not specified, the lowest common ancestor of all input entry point paths, i.e. `src/utils`, is used by default, and the final file output structure is:
+
+```txt
+dist
+├── bar
+│   └── index.js
+├── foo
+│   └── index.js
+└── index.js
+```
+
+When `outBase` is configured as `./src`, the output directory structure is:
+
+```txt
+dist
+└── utils
+    ├── bar
+    │   └── index.js
+    ├── foo
+    │   └── index.js
+    └── index.js
+```

website/docs/en/config/lib/out-base.mdx

@@ -1,4 +1,4 @@
-# Tsup
+# tsup
 
 This section introduces how to migrate a project using tsup to Rslib.
 

website/docs/en/guide/migration/tsup.mdx

@@ -11,5 +11,6 @@
   "dts",
   "shims",
   "id",
-  "umd-name"
+  "umd-name",
+  "out-base"
 ]

website/docs/zh/config/lib/_meta.json

@@ -1,7 +1,7 @@
 # lib.bundle
 
 - **类型：** `boolean`
-- **默认值：** `undefined`
+- **默认值：** `true`
 
 指定是否打包库，当 `bundle` 设置为 `true` 时称为 bundle 模式，设置为 `false` 时称为 bundleless 模式。更多详情请参考 [bundle / bundleless](/guide/basic/output-structure#bundle--bundleless)。