feat(config): support shared configs with define.extends (#544)

Author: chenjiahan

packages/rstack/src/config.ts

@@ -13,37 +13,35 @@ import type { UserConfig, UserConfigAsyncFn } from '@rspress/core';
 import type { RstestConfigExport } from '@rstest/core';
 import type { FmtConfigDefinition } from './fmt/types.ts';
 import type { StagedConfig } from './staged.ts';
-import { composeConfigLayers } from './configLayers.ts';
+import { composeConfigLayers, flattenConfigLayers } from './configLayers.ts';
 
-export type RslintConfigDefinition =
-  RslintConfig | (() => Promise<RslintConfig>);
 export type RspressConfigDefinition = UserConfig | UserConfigAsyncFn;
 
 type RslintConfigFactory = (
   lint: typeof import('@rslint/core'),
 ) => RslintConfig | Promise<RslintConfig>;
 
-type RslintConfigInput = RslintConfig | RslintConfigFactory;
+export type RslintConfigDefinition = RslintConfig | RslintConfigFactory;
 
 export type Configs = {
   app?: RsbuildConfigDefinition;
   lib?: RslibConfigDefinition;
   doc?: RspressConfigDefinition;
   test?: RstestConfigExport;
-  lint?: RslintConfigDefinition;
+  lint?: RslintConfig | (() => Promise<RslintConfig>);
   fmt?: FmtConfigDefinition;
   staged?: StagedConfig;
 };
 
 /** Shared configuration input; lint factories receive the tool exports. */
 export type RstackConfig = Omit<Configs, 'lint'> & {
   extends?: readonly RstackConfig[];
-  lint?: RslintConfigInput;
+  lint?: RslintConfigDefinition;
 };
 
 const normalizeLintConfig = (
-  config: RslintConfigInput,
-): RslintConfigDefinition =>
+  config: RslintConfigDefinition,
+): NonNullable<Configs['lint']> =>
   typeof config === 'function'
     ? async () => config(await import('@rslint/core'))
     : config;
@@ -82,6 +80,7 @@ export type LoadRstackConfigOptions = {
 
 type ConfigSession = {
   configs: Configs;
+  extends?: readonly RstackConfig[];
   active: boolean;
 };
 
@@ -125,6 +124,13 @@ export const getConfigState = (): ConfigState => {
 };
 
 type Define = {
+  /**
+   * Inherits shared configs from left to right, followed by the project's own
+   * definitions regardless of call order. May only be called once per config load.
+   *
+   * @see {@link https://rstack.rs/config | Configuration guide}
+   */
+  extends: (configs: readonly RstackConfig[]) => void;
   /**
    * Defines the Rsbuild config for the app.
    *
@@ -169,7 +175,7 @@ type Define = {
    *
    * @see {@link https://rstack.rs/config | Configuration guide}
    */
-  lint: (config: RslintConfigInput) => void;
+  lint: (config: RslintConfigDefinition) => void;
   /**
    * Defines the Prettier config for formatting.
    *
@@ -207,6 +213,18 @@ const setConfig = <T extends keyof Configs>(
 };
 
 export const define: Define = {
+  extends: (configs) => {
+    const session = getConfigSessionStorage().getStore();
+    if (!session?.active) {
+      throw new Error(
+        'The "extends" config must be defined while loading an Rstack config.',
+      );
+    }
+    if (session.extends !== undefined) {
+      throw new Error('The "extends" config has already been defined.');
+    }
+    session.extends = configs;
+  },
   app: ((config) => {
     setConfig('app', config);
     return config;
@@ -253,13 +271,19 @@ export const loadRstackConfig = async ({
       });
 
       return {
-        configs: await composeConfigLayers([session.configs]),
+        configs: session.extends?.length
+          ? await composeConfigLayers([
+              ...flattenConfigLayers(session.extends),
+              session.configs,
+            ])
+          : session.configs,
         filePath,
         dependencies,
       };
     } finally {
       session.active = false;
       session.configs = {};
+      session.extends = undefined;
     }
   });
 };

packages/rstack/src/index.ts

@@ -1,2 +1,2 @@
-export { define } from './config.ts';
+export { define, type RstackConfig } from './config.ts';
 export { runCLI } from './cli/index.ts';

packages/rstack/tests/config/extends/after.config.ts

@@ -0,0 +1,10 @@
+import { define } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+define.extends([
+  sharedConfig,
+  {
+    fmt: { printWidth: 80 },
+  },
+]);
+define.fmt({ singleQuote: false });

packages/rstack/tests/config/extends/index.test.ts

@@ -0,0 +1,61 @@
+import path from 'node:path';
+import { expect, test } from 'rstack/test';
+import { loadRstackConfig } from '../../../src/config.ts';
+import { resolveConfigLayers } from '../../../src/configLayers.ts';
+
+const cwd = import.meta.dirname;
+const params = { command: 'build', env: 'production' } as const;
+
+test('loads all seven tools from shared configs and tracks their dependencies', async () => {
+  const { configs, filePath, dependencies } = await loadRstackConfig({ cwd });
+  const layers = [configs];
+
+  expect({
+    app: await resolveConfigLayers(layers, 'app', params),
+    lib: await resolveConfigLayers(layers, 'lib', params),
+    doc: await resolveConfigLayers(layers, 'doc'),
+    test: await resolveConfigLayers(layers, 'test'),
+    lint: await resolveConfigLayers(layers, 'lint'),
+    fmt: await resolveConfigLayers(layers, 'fmt'),
+    staged: await resolveConfigLayers(layers, 'staged'),
+  }).toEqual({
+    app: [
+      {
+        source: {
+          define: { ENV: 'production' },
+        },
+      },
+    ],
+    lib: [
+      {
+        lib: [{ format: 'esm' }],
+      },
+    ],
+    doc: [{ root: 'docs' }],
+    test: [{ setupFiles: [path.join(cwd, 'setup.ts')] }],
+    lint: [
+      [
+        {
+          rules: { 'no-debugger': 'error' },
+        },
+      ],
+    ],
+    fmt: [{ semi: false, singleQuote: false, printWidth: 80 }],
+    staged: [{ '*.ts': 'rs lint' }],
+  });
+  expect(filePath).toBe(path.join(cwd, 'rstack.config.ts'));
+  expect(dependencies).toContain(path.join(cwd, 'shared.ts'));
+});
+
+test('preserves project priority regardless of call order and across reloads', async () => {
+  for (const configFilePath of [
+    'rstack.config.ts',
+    'after.config.ts',
+    'rstack.config.ts',
+  ]) {
+    const { configs } = await loadRstackConfig({ cwd, configFilePath });
+    expect(await resolveConfigLayers([configs], 'fmt')).toEqual([
+      { semi: false, singleQuote: false, printWidth: 80 },
+    ]);
+  }
+});

packages/rstack/tests/config/extends/rstack.config.ts

@@ -0,0 +1,10 @@
+import { define } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+define.fmt({ singleQuote: false });
+define.extends([
+  sharedConfig,
+  {
+    fmt: { printWidth: 80 },
+  },
+]);

packages/rstack/tests/config/extends/shared.ts

@@ -0,0 +1,28 @@
+import { fileURLToPath } from 'node:url';
+import type { RstackConfig } from 'rstack';
+
+export const sharedConfig: RstackConfig = {
+  extends: [
+    {
+      fmt: { semi: false, printWidth: 100 },
+    },
+  ],
+  app: ({ env }) => ({
+    source: {
+      define: { ENV: env },
+    },
+  }),
+  lib: {
+    lib: [{ format: 'esm' }],
+  },
+  doc: { root: 'docs' },
+  test: { setupFiles: [fileURLToPath(new URL('./setup.ts', import.meta.url))] },
+  lint: ({ defineConfig }) =>
+    defineConfig([
+      {
+        rules: { 'no-debugger': 'error' },
+      },
+    ]),
+  fmt: { singleQuote: true },
+  staged: { '*.ts': 'rs lint' },
+};

packages/rstack/tests/config/load-config/duplicate-extends.config.ts

@@ -0,0 +1,4 @@
+import { define } from 'rstack';
+
+define.extends([]);
+define.extends([]);

packages/rstack/tests/config/load-config/index.test.ts

@@ -1,6 +1,10 @@
 import path from 'node:path';
 import { afterEach, expect, test } from 'rstack/test';
-import { getConfigState, loadRstackConfig } from '../../../src/config.ts';
+import {
+  define,
+  getConfigState,
+  loadRstackConfig,
+} from '../../../src/config.ts';
 
 type Deferred = ReturnType<typeof Promise.withResolvers<void>>;
 
@@ -37,7 +41,9 @@ test('should discard a config session after loading fails', async () => {
   await expect(loadRstackConfig()).rejects.toThrow('test config error');
 
   const { configs } = await loadConfigFile('explicit.config.ts');
-  expect(configs).toEqual({ app: {} });
+  expect(configs).toEqual({
+    app: {},
+  });
 });
 
 test('should prefer an explicit config path over the state config path', async () => {
@@ -111,3 +117,18 @@ test('should reject duplicate definitions within the same session', async () =>
     'The "app" config has already been defined.',
   );
 });
+
+test('rejects repeated extends calls even with empty arrays', async () => {
+  await expect(loadConfigFile('duplicate-extends.config.ts')).rejects.toThrow(
+    'The "extends" config has already been defined.',
+  );
+  expect((await loadConfigFile('explicit.config.ts')).configs).toEqual({
+    app: {},
+  });
+});
+
+test('rejects extends outside a config load', () => {
+  expect(() => define.extends([])).toThrow(
+    'The "extends" config must be defined while loading an Rstack config.',
+  );
+});

packages/rstack/tests/types/resolution-bundler/index.ts

@@ -2,7 +2,7 @@
 import 'rstack/test/globals';
 import 'rstack/test/importMeta';
 import 'rstack/types';
-import { define } from 'rstack';
+import { define, type RstackConfig } from 'rstack';
 import { createRsbuild, defineConfig as defineAppConfig } from 'rstack/app';
 import {
   loadRstackConfig,
@@ -22,6 +22,11 @@ const loadOptions: LoadRstackConfigOptions = {
 };
 const loadedConfig: Promise<LoadedRstackConfig> = loadRstackConfig(loadOptions);
 const configs: Configs = {};
+const sharedConfig: RstackConfig = {
+  app: appConfig,
+  lint: lintConfig,
+};
+define.extends([{ extends: [sharedConfig] }] as const);
 
 void loadedConfig;
 void configs;
@@ -50,11 +55,15 @@ define.lib(() => ({
   lib: [
     {
       format: 'esm',
-      source: { entry: { index: './src/index.ts' } },
+      source: {
+        entry: { index: './src/index.ts' },
+      },
     },
     {
       format: 'esm',
-      source: { entry: { worker: './src/worker.ts' } },
+      source: {
+        entry: { worker: './src/worker.ts' },
+      },
     },
   ],
 }));

packages/rstack/tests/types/resolution-nodenext/index.ts

@@ -2,7 +2,7 @@
 import 'rstack/test/globals';
 import 'rstack/test/importMeta';
 import 'rstack/types';
-import { define } from 'rstack';
+import { define, type RstackConfig } from 'rstack';
 import { createRsbuild, defineConfig as defineAppConfig } from 'rstack/app';
 import {
   loadRstackConfig,
@@ -22,6 +22,11 @@ const loadOptions: LoadRstackConfigOptions = {
 };
 const loadedConfig: Promise<LoadedRstackConfig> = loadRstackConfig(loadOptions);
 const configs: Configs = {};
+const sharedConfig: RstackConfig = {
+  app: appConfig,
+  lint: lintConfig,
+};
+define.extends([{ extends: [sharedConfig] }] as const);
 
 void loadedConfig;
 void configs;
@@ -50,11 +55,15 @@ define.lib(() => ({
   lib: [
     {
       format: 'esm',
-      source: { entry: { index: './src/index.ts' } },
+      source: {
+        entry: { index: './src/index.ts' },
+      },
     },
     {
       format: 'esm',
-      source: { entry: { worker: './src/worker.ts' } },
+      source: {
+        entry: { worker: './src/worker.ts' },
+      },
     },
   ],
 }));