RFC: A unified way to extend Rstack configuration

[chenjiahan]

Background

Rstack CLI already provides a single configuration entry point through rstack.config.* and the define.* APIs, but it lacks a unified way to extend configuration across tools.

Today, developer infrastructure teams and plugin authors extend Rstack CLI through mechanisms such as Rsbuild plugins. These mechanisms are specific to individual tools and do not provide a single way to configure linting, testing, and formatting alongside the build.

As a result, users may need to add plugins or configuration separately to define.app, define.lib, and define.lint to integrate an extension across their toolchain.

This RFC proposes define.extends(), which lets projects inherit shared configuration for multiple tools at once. Shared configurations can capture team conventions, provide framework defaults, and be reused across a monorepo.

Example use cases:

• Developer infrastructure teams: Provide two standard presets, app-preset and lib-preset, for applications and libraries in a monorepo. Each preset covers the appropriate build, test, lint, and formatting configuration.
• Plugin authors: Zack is building a tool that collects context from across the Rstack toolchain so that AI agents can use information from the development workflow. Each tool has its own configuration and extension mechanisms, making it difficult to provide a single integration that works across Rstack CLI.

Prior art

Several tools in the JavaScript ecosystem offer ways to inherit or compose configuration.

ESLint

ESLint uses configuration arrays and extends to compose shared configurations. Configurations are applied in order, with later entries able to override earlier ones. Users can also import and compose configuration objects directly. See the ESLint configuration documentation.

// eslint.config.mjs
import js from '@eslint/js';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  {
    extends: [js.configs.recommended],
    rules: { 'no-unused-vars': 'warn' },
  },
]);

Nuxt

Nuxt uses Layers to share configuration and application resources. A layer is a reusable foundation for a Nuxt application. It can include configuration, components, pages, layouts, and utilities, with a directory structure similar to a regular Nuxt application.

Nuxt uses extends to declare which layers a project inherits from. The project's own configuration has the highest priority. See Nuxt Layers.

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['./base'], // Inherit configuration from ./base/nuxt.config.ts
  ssr: false,
});

Next.js

Next.js integrations often use functions that wrap configuration objects. For example, withMDX(nextConfig) returns an extended configuration.

This approach is flexible, but users need to manage the order when composing multiple wrappers. See the Next.js MDX documentation.

// next.config.mjs
import createMDX from '@next/mdx';

const withMDX = createMDX({});

export default withMDX({
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'mdx'],
});

Of these approaches, extends is the best fit for Rstack CLI: users only need to understand shared configurations and their order of precedence.

Rspack CLI and Rstest already provide an extends configuration field, so this approach follows familiar APIs in the Rstack ecosystem.

Design principles

• Avoid introducing another plugin system. The Rstack ecosystem already has several, including those in Rspack, Rsbuild, and Rspress.
• Use familiar concepts to make the extension mechanism easy for developers and AI agents to understand.
• Keep the design simple and leave room for future extensions.
• Extending the CLI with custom commands, such as rs mcp, is outside the scope of this RFC. If needed, we can explore an API such as define.command() separately.

Configuration example

A developer infrastructure team can define shared configuration for builds, tests, and linting:

// shared-config/index.ts
import type { RstackConfig } from 'rstack';

export const sharedConfig: RstackConfig = {
  app: async () => {
    const { pluginReact } = await import('@rsbuild/plugin-react');
    return {
      plugins: [
        pluginReact({
          reactCompiler: true,
        }),
      ],
    };
  },
  test: {
    setupFiles: ['./tests/rstest.setup.ts'],
  },
  lint: ({ js, ts, reactPlugin }) => [
    js.configs.recommended,
    ts.configs.recommended,
    reactPlugin.configs.recommended,
  ],
};

A project can then inherit the shared configuration in rstack.config.ts and add its own settings:

import { define } from 'rstack';
import { sharedConfig } from 'shared-config';

define.extends([sharedConfig]);

define.app({
  // Project-specific settings
});

API design

define.extends()

Use define.extends() to inherit one or more shared configurations. Build plugins in shared configurations are still registered through existing fields such as app.plugins and lib.plugins.

Like the other define.* methods, define.extends() can be called at most once per configuration load. Calling it more than once throws an error.

RstackConfig

The RstackConfig type describes a shared configuration. Each tool's field accepts exactly the same input as its corresponding define method:

type RstackConfig = {
  // Support nested inheritance
  extends?: readonly RstackConfig[];
  app?: RsbuildConfigDefinition;
  lib?: RslibConfigDefinition;
  doc?: RspressConfigDefinition;
  test?: RstestConfigDefinition;
  lint?: RslintConfigDefinition;
  fmt?: FmtConfigDefinition;
  staged?: StagedConfigDefinition;
};

Shared configurations

A shared configuration can be a plain object:

import type { RstackConfig } from 'rstack';

export const sharedConfig: RstackConfig = {
  test: {
    retry: 2,
  },
  fmt: {
    singleQuote: true,
    printWidth: 80,
  },
};

Each field follows the same conventions as its corresponding define method. For example, app accepts the same input as define.app:

import type { RstackConfig } from 'rstack';

export const sharedConfig: RstackConfig = {
  app: async () => {
    const { pluginReact } = await import('@rsbuild/plugin-react');
    return { plugins: [pluginReact()] };
  },
};

Shared configurations can also be created by ordinary functions, allowing consumers to customize them through arguments:

import type { RstackConfig } from 'rstack';

export function sharedConfig(
  options: { testEnvironment?: 'node' | 'jsdom' } = {},
): RstackConfig {
  return {
    test: {
      testEnvironment: options.testEnvironment ?? 'jsdom',
    },
    lint: ({ js, ts }) => [js.configs.recommended, ts.configs.recommended],
  };
}

Consumers can call sharedConfig({ testEnvironment: 'node' }) to create a configuration with their preferred options.

Merge rules

Configurations are merged in the following order:

1. Shared configurations passed to define.extends(), from left to right.
2. The project's own configuration registered through the define methods.

Each tool uses its own merge rules:

Field	Merge behavior
app	Use Rsbuild's mergeRsbuildConfig.
lib	Use Rslib's mergeRslibConfig.
test	Use Rstest's mergeRstestConfig.
lint	Concatenate configuration arrays and let Rslint apply its existing merge logic.
fmt	Start with a shallow merge. Consider a dedicated merge helper for options such as Prettier's overrides.
doc	Deep merge. Consider a dedicated merge helper from Rspress.
staged	Shallow merge by glob pattern.

Test configuration inheritance

Currently, define.test() automatically inherits the application or library configuration when extends is not explicitly set.

With shared configurations, the test configuration must first be resolved and merged across layers before deciding whether to apply automatic inheritance.

The process is:

1. Resolve and merge the test configuration from all layers.
2. Check extends and projects in the merged result to determine whether automatic inheritance is needed.
3. If needed, resolve and merge the app configuration. Fall back to lib only if no layer defines app.
4. Apply inheritance through the existing Rstest adapters.

Path resolution

Relative paths in shared configurations continue to follow each tool's existing resolution rules. Different tools may resolve paths relative to different base directories.

For example, a shared configuration that ships its own test setup file should reference it with an absolute path:

import { fileURLToPath } from 'node:url';
import type { RstackConfig } from 'rstack';

export const sharedConfig: RstackConfig = {
  test: {
    setupFiles: [fileURLToPath(new URL('./setup.ts', import.meta.url))],
  },
};

Nested inheritance

A shared configuration can inherit other shared configurations:

import type { RstackConfig } from 'rstack';
import { baseConfig } from './base.ts';
import { reactConfig } from './react.ts';

export const sharedConfig: RstackConfig = {
  extends: [baseConfig, reactConfig],
  test: {
    retry: 2,
  },
};

Nested configurations are expanded depth-first: inherited configurations are applied before the object that extends them. In this example, the order is baseConfig → reactConfig → sharedConfig, followed by the consuming project's own configuration registered through the define methods.

Considerations

• Merge rules vary by tool. Each tool has its own field semantics and merge behavior.
• Modifying the final merged configuration is out of scope. This proposal does not add an API for modifying configuration after merging. We can revisit this if concrete use cases emerge.
• Shared configurations must also load dependencies lazily. Use dynamic import() calls inside configuration functions to load plugins and third-party packages without adding unnecessary startup overhead.