Docs
Blog
Docs
Blog

Rspack configuration via extension.config.js

Customize bundling behavior without leaving the Extension.js workflow.

Solve custom bundler needs (loaders, plugins, aliases) without forking the default setup. Extension.js builds with Rspack (@rspack/core) and lets you extend the generated config directly.

How it works

Create one of these files at project root:

  • extension.config.js
  • extension.config.mjs
  • extension.config.cjs

Use the config key to patch generated bundler config.

config capabilities

Capability What it does
Function hook (config: (config) => config) Gives full control to read and modify generated Rspack config before build.
Object merge (config: { ... }) Merges additional config into the generated base config.
Rules (config.module.rules) Adds or changes loader rules for file types.
Plugins (config.plugins) Adds compile-time plugins and transformations.
Resolve (config.resolve) Adds aliases and module resolution behavior.

Option 1: function hook (recommended)

export default {
  config: (config) => {
    config.module.rules.push({
      test: /\.mdx$/,
      use: ["babel-loader", "@mdx-js/loader"],
    });
    return config;
  },
};

Video demo soon: function hook customization

Option 2: object merge

config can also be an object. Extension.js merges it into the base config.

export default {
  config: {
    resolve: {
      alias: {
        "@ui": "/absolute/path/to/ui",
      },
    },
  },
};

Video demo soon: object merge customization

Rspack-first, webpack-compatible

Extension.js is Rspack-native, but much of the webpack ecosystem is still usable.

  • Config type is based on @rspack/core Configuration.
  • Many webpack loaders/plugins work through compatibility layers.
  • Some webpack internals/plugins are not 1:1 compatible with Rspack.

Example using a Rspack-native plugin:

import { DefinePlugin } from "@rspack/core";

export default {
  config: (config) => {
    config.plugins = [
      ...config.plugins,
      new DefinePlugin({
        __FEATURE_FLAG__: JSON.stringify("enabled"),
      }),
    ];
    return config;
  },
};

Video demo soon: rspack plugin usage

When to use this

  • Add custom loaders/rules for project-specific file types.
  • Add plugins for compile-time transforms and diagnostics.
  • Override resolve aliases and module behavior not exposed by first-class Extension.js options.

Best practices

  • Prefer first-class options first: Use browser / commands config keys before low-level bundler overrides.
  • Patch minimally: Change only the pieces you need, then return the config.
  • Keep plugins Rspack-aware: Prefer Rspack-native plugins when available.
  • Verify on all targets: Test dev, start, preview, and build for your browser matrix after config changes.

Next steps

ON THIS PAGE