CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-rsbuild--core

The Rspack-based build tool providing high-performance bundling with comprehensive development features and plugin system.

—

Pending
Overview
Eval results
Files

configuration-management.mddocs/

Configuration Management

Configuration loading, definition, and merging utilities for Rsbuild. Handles both file-based and programmatic configuration with TypeScript support and environment-specific settings.

Capabilities

Define Configuration

Type-safe configuration helper function that provides IntelliSense and type checking for Rsbuild configurations.

/**
 * Type-safe configuration helper with IntelliSense support
 * @param config - Rsbuild configuration object or function
 * @returns The same configuration for use with createRsbuild
 */
function defineConfig(config: RsbuildConfigExport): RsbuildConfigExport;

type RsbuildConfigExport =
  | RsbuildConfig
  | RsbuildConfigSyncFn
  | RsbuildConfigAsyncFn;

type RsbuildConfigSyncFn = (env: ConfigParams) => RsbuildConfig;
type RsbuildConfigAsyncFn = (env: ConfigParams) => Promise<RsbuildConfig>;

interface ConfigParams {
  /** Current environment mode */
  env: string;
  /** CLI command being executed */
  command: string;
  /** Environment mode override */
  envMode?: string;
  /** Custom metadata passed to config */
  meta?: Record<string, unknown>;
}

Usage Examples:

import { defineConfig } from "@rsbuild/core";

// Static configuration
export default defineConfig({
  source: {
    entry: {
      index: "./src/index.ts",
    },
  },
  output: {
    target: "web",
  },
});

// Dynamic configuration with environment
export default defineConfig(({ env, command }) => {
  const isDev = env === "development";
  
  return {
    source: {
      entry: {
        index: "./src/index.ts",
      },
    },
    output: {
      target: "web",
      minify: !isDev,
    },
    dev: {
      hmr: isDev,
    },
  };
});

// Async configuration
export default defineConfig(async ({ env }) => {
  const apiConfig = await fetchConfigFromAPI(env);
  
  return {
    source: {
      entry: apiConfig.entries,
    },
    output: {
      target: apiConfig.target,
    },
  };
});

Load Configuration File

Loads Rsbuild configuration from file with support for TypeScript, ESM, and CommonJS formats.

/**
 * Load Rsbuild configuration from file
 * @param options - Configuration loading options
 * @returns Promise resolving to loaded configuration result
 */
function loadConfig(options?: LoadConfigOptions): Promise<LoadConfigResult>;

interface LoadConfigOptions {
  /** Root path for config file resolution */
  cwd?: string;
  /** Specific config file path (relative or absolute) */
  path?: string;
  /** Custom metadata to pass to config function */
  meta?: Record<string, unknown>;
  /** Environment mode for config function */
  envMode?: string;
  /** Configuration loader to use */
  configLoader?: 'jiti' | 'native';
}

interface LoadConfigResult {
  /** Loaded configuration object */
  config: RsbuildConfig;
  /** Path to the loaded config file */
  filePath?: string;
  /** Environment variables loaded with config */
  loadedEnv?: Record<string, string>;
}

Default Config File Resolution:

Rsbuild searches for config files in this order:

  1. rsbuild.config.ts
  2. rsbuild.config.js
  3. rsbuild.config.mjs
  4. rsbuild.config.mts
  5. rsbuild.config.cts
  6. rsbuild.config.cjs

Usage Examples:

import { loadConfig } from "@rsbuild/core";

// Load from default location
const { config } = await loadConfig();

// Load from specific file
const { config, filePath } = await loadConfig({
  path: "./config/rsbuild.prod.config.ts",
});

// Load with custom working directory
const { config } = await loadConfig({
  cwd: "/path/to/project",
});

// Load with custom metadata
const { config } = await loadConfig({
  meta: {
    buildId: "12345",
    deployEnv: "staging",
  },
});

// Use native Node.js loader (requires Node.js >= 22.6)
const { config } = await loadConfig({
  configLoader: "native",
});

Merge Configurations

Merges multiple Rsbuild configuration objects with deep merging and array handling.

/**
 * Merge multiple Rsbuild configurations with deep merging
 * @param configs - Configuration objects to merge
 * @returns Merged configuration object
 */
function mergeRsbuildConfig(...configs: RsbuildConfig[]): RsbuildConfig;

Merge Behavior:

  • Objects are deeply merged
  • Arrays are concatenated
  • Later values override earlier ones for primitives
  • Plugins arrays are merged and deduplicated by name

Usage Examples:

import { mergeRsbuildConfig } from "@rsbuild/core";

const baseConfig = {
  source: {
    entry: { index: "./src/index.ts" },
    alias: { "@": "./src" },
  },
  output: {
    target: "web",
  },
};

const devConfig = {
  dev: {
    hmr: true,
  },
  output: {
    sourceMap: true,
  },
};

const prodConfig = {
  output: {
    minify: true,
    sourceMap: false,
  },
  performance: {
    chunkSplit: {
      strategy: "split-by-experience",
    },
  },
};

// Merge configurations
const developmentConfig = mergeRsbuildConfig(baseConfig, devConfig);
const productionConfig = mergeRsbuildConfig(baseConfig, prodConfig);

// Merge multiple configs
const finalConfig = mergeRsbuildConfig(
  baseConfig,
  environmentConfig,
  featureConfig,
  userConfig
);

Configuration Structure

Main Configuration Interface

interface RsbuildConfig {
  /** Build mode */
  mode?: 'development' | 'production' | 'none';
  /** Project root directory */
  root?: string;
  /** Logging level */
  logLevel?: 'silent' | 'error' | 'warn' | 'info' | 'debug';
  /** Environment-specific configurations */
  environments?: Record<string, EnvironmentConfig>;
  /** Source code configuration */
  source?: SourceConfig;
  /** Build output configuration */
  output?: OutputConfig;
  /** HTML generation configuration */
  html?: HtmlConfig;
  /** Build tools configuration */
  tools?: ToolsConfig;
  /** Development configuration */
  dev?: DevConfig;
  /** Development server configuration */
  server?: ServerConfig;
  /** Security configuration */
  security?: SecurityConfig;
  /** Performance optimization configuration */
  performance?: PerformanceConfig;
  /** Module Federation configuration */
  moduleFederation?: ModuleFederationConfig;
  /** Plugin list */
  plugins?: RsbuildPlugins;
  /** Bundler provider configuration */
  provider?: unknown;
}

Source Configuration

interface SourceConfig {
  /** Entry points configuration */
  entry?: RsbuildEntry;
  /** Module path aliases */
  alias?: Record<string, string | false> | ((aliases: Record<string, string>) => Record<string, string>);
  /** Global variable definitions */
  define?: Record<string, string | boolean | undefined>;
  /** Files to include in compilation */
  include?: (string | RegExp)[];
  /** Files to exclude from compilation */
  exclude?: (string | RegExp)[];
  /** TypeScript decorator configuration */
  decorators?: {
    version?: '2018-09' | 'legacy';
    metadata?: boolean;
  };
  /** Import transformation rules */
  transformImport?: TransformImport[];
}

interface TransformImport {
  libraryName: string;
  libraryDirectory?: string;
  style?: boolean | string;
  styleLibraryDirectory?: string;
  camel2DashComponentName?: boolean;
  camel2UnderlineComponentName?: boolean;
  transformToDefaultImport?: boolean;
}

type RsbuildEntry = string | string[] | Record<string, string | string[] | RsbuildEntryDescription>;

interface RsbuildEntryDescription {
  import: string | string[];
  filename?: string;
  runtime?: string;
  publicPath?: string;
}

Output Configuration

interface OutputConfig {
  /** Build target platform */
  target?: RsbuildTarget | RsbuildTarget[];
  /** Output directory paths */
  distPath?: DistPathConfig;
  /** Output file naming patterns */
  filename?: FilenameConfig;
  /** Source map generation */
  sourceMap?: SourceMap;
  /** Code minification settings */
  minify?: Minify;
  /** Polyfill injection */
  polyfill?: Polyfill;
  /** External dependencies */
  externals?: Externals;
  /** Asset URL prefix */
  assetPrefix?: string | ((params: { target: RsbuildTarget; environment: string }) => string);
  /** Output charset */
  charset?: 'ascii' | 'utf8';
  /** Clean output directory */
  cleanDistPath?: boolean | CleanDistPathObject;
  /** File copying configuration */
  copy?: CopyConfig[];
  /** Data URI size limits */
  dataUriLimit?: DataUriLimit;
  /** Legal comment handling */
  legalComments?: 'none' | 'inline' | 'linked';
}

type RsbuildTarget = 'web' | 'node' | 'web-worker';
type SourceMap = boolean | 'inline' | 'hidden';
type Minify = boolean | 'terser' | 'swc' | 'esbuild';
type Polyfill = 'entry' | 'usage' | 'off';

interface DistPathConfig {
  root?: string;
  js?: string;
  css?: string;
  svg?: string;
  font?: string;
  html?: string;
  image?: string;
  media?: string;
  worker?: string;
}

interface FilenameConfig {
  js?: string;
  css?: string;
  svg?: string;
  font?: string;
  image?: string;
  media?: string;
}

Development Configuration

interface DevConfig {
  /** Hot Module Replacement */
  hmr?: boolean | HMROptions;
  /** Live reload on file changes */
  liveReload?: boolean;
  /** Asset prefix for development */
  assetPrefix?: string | 'auto';
  /** Client-side configuration */
  client?: ClientConfig;
  /** Progress bar display */
  progressBar?: boolean | ProgressBarConfig;
  /** Lazy compilation settings */
  lazyCompilation?: boolean | LazyCompilationOptions;
}

interface HMROptions {
  port?: number;
  host?: string;
  path?: string;
}

interface ClientConfig {
  protocol?: 'ws' | 'wss';
  port?: number;
  host?: string;
  path?: string;
  overlay?: boolean | OverlayOptions;
}

interface OverlayOptions {
  errors?: boolean;
  warnings?: boolean;
}

Server Configuration

interface ServerConfig {
  /** Server port */
  port?: number;
  /** Server host */
  host?: string;
  /** HTTPS configuration */
  https?: boolean | HTTPSOptions;
  /** Proxy configuration */
  proxy?: ProxyConfig;
  /** CORS settings */
  cors?: boolean | CorsOptions;
  /** Custom response headers */
  headers?: Record<string, string>;
  /** History API fallback for SPAs */
  historyApiFallback?: boolean | HistoryApiFallbackOptions;
  /** Response compression */
  compress?: boolean | CompressOptions;
  /** Auto-open browser */
  open?: boolean | string | OpenOptions;
  /** Base URL path */
  base?: string;
  /** Static file serving */
  publicDir?: PublicDir;
  /** Custom middleware setup */
  setupMiddlewares?: SetupMiddlewaresFn;
}

interface HTTPSOptions {
  key?: string;
  cert?: string;
}

interface ProxyConfig {
  [path: string]: string | ProxyOptions;
}

interface ProxyOptions {
  target: string;
  changeOrigin?: boolean;
  pathRewrite?: Record<string, string>;
  onProxyReq?: Function;
  onProxyRes?: Function;
}

Performance Configuration

interface PerformanceConfig {
  /** Bundle analysis */
  bundleAnalyze?: BundleAnalyzeOptions;
  /** Code splitting strategy */
  chunkSplit?: ChunkSplitOptions;
  /** Resource preloading */
  preload?: boolean | PreloadOptions;
  /** Resource prefetching */
  prefetch?: boolean | PrefetchOptions;
  /** DNS preconnection */
  preconnect?: PreconnectOption[];
  /** DNS prefetching */
  dnsPrefetch?: string[];
  /** Console removal in production */
  removeConsole?: boolean | RemoveConsoleOptions;
  /** Remove Moment.js locales */
  removeMomentLocale?: boolean;
  /** Build caching */
  buildCache?: boolean | BuildCacheOptions;
}

interface ChunkSplitOptions {
  strategy?: 'split-by-experience' | 'split-by-module' | 'all-in-one' | 'single-vendor';
  minSize?: number;
  maxSize?: number;
  chunks?: 'async' | 'initial' | 'all';
  enforce?: boolean;
  cacheGroups?: Record<string, CacheGroupOptions>;
}

Environment-Specific Configuration

interface EnvironmentConfig {
  /** Source configuration for this environment */
  source?: SourceConfig;
  /** Output configuration for this environment */
  output?: OutputConfig;
  /** HTML configuration for this environment */
  html?: HtmlConfig;
  /** Tools configuration for this environment */
  tools?: ToolsConfig;
  /** Development configuration for this environment */
  dev?: DevConfig;
  /** Server configuration for this environment */
  server?: ServerConfig;
  /** Security configuration for this environment */
  security?: SecurityConfig;
  /** Performance configuration for this environment */
  performance?: PerformanceConfig;
  /** Module Federation configuration for this environment */
  moduleFederation?: ModuleFederationConfig;
}

Usage Examples:

export default defineConfig({
  // Global configuration
  source: {
    alias: {
      "@": "./src",
    },
  },
  
  // Environment-specific configurations
  environments: {
    web: {
      output: {
        target: "web",
      },
      html: {
        template: "./src/web.html",
      },
    },
    
    node: {
      output: {
        target: "node",
      },
      tools: {
        rspack: {
          externals: nodeExternals(),
        },
      },
    },
    
    mobile: {
      output: {
        target: "web",
        assetPrefix: "https://cdn.example.com/mobile/",
      },
      performance: {
        chunkSplit: {
          strategy: "all-in-one",
        },
      },
    },
  },
});

Install with Tessl CLI

npx tessl i tessl/npm-rsbuild--core

docs

cli-integration.md

configuration-management.md

core-build-system.md

development-server.md

environment-system.md

environment-variables.md

index.md

plugin-system.md

tile.json