@rspack/core), and you can extend the generated configuration directly.
How it works
Create one of these files at project root:extension.config.jsextension.config.mjsextension.config.cjs
config key to patch the generated bundler configuration.
config capabilities
Option 1: function hook (recommended)
Option 2: object merge
config can also be an object. Extension.js merges it into the base configuration.
Rspack-first, webpack-compatible
Extension.js is Rspack-native, but you can still use much of the webpack ecosystem.- The config type extends
@rspack/coreConfiguration. - Many webpack loaders/plugins work through compatibility layers.
- Some webpack internals/plugins are not 1:1 compatible with Rspack.
rspack, the bundler that Extension.js compiles with. Take plugin classes from it, so your project needs no @rspack/core of its own:
@rspack/core. See the hook context for every field of that argument, and Node APIs in browser extensions for the resolve.fallback recipe.
The bundler name in diagnostics
Build output says Extension.js where the bundler’s own text says Rspack, because Extension.js is the tool that you run. From the release after 4.1.39, a name that you type stays as written. That covers text in backticks, the quoted key"rspack", the destructured {rspack}, and a member such as rspack.ProvidePlugin. You can paste a line such as new rspack.NormalModuleReplacementPlugin(...) from a diagnostic as printed.
Share a module between entries
Extension.js splits HTML pages only. The defaultoptimization.splitChunks gives pages two stable siblings: shared/framework.js for the UI framework runtime, and shared/commons.js for anything two or more pages import. The framework group covers React, Preact, Vue, Svelte and Lit. Neither name carries a hash, so a manifest entry or a public asset can keep pointing at it.
From the release after 4.1.39, a Firefox build ships a shared file past 4 MB as numbered parts, such as shared/commons-0.js. See Firefox builds split large files.
Every other surface keeps exactly one file. The manifest names a single script for a background worker, a content script or an injected script, and those surfaces never load a sibling.
That is why sharing a module between a page and a content script still needs import(). Rspack emits one chunk for it, and every caller fetches that chunk on demand from the extension origin. A cache group gives the chunk a stable name:
await import("../shared/big") from the popup and from the options page both resolve to one emitted shared.js. Keep chunks at "async". A sync split moves code out of an entry file. The emitted HTML and the manifest reference only that entry file, so the page never loads the split chunk. The service worker keeps its own copy of the module, because it cannot fetch a chunk after it installs. A content script can share the chunk too, but it must expose the file through web_accessible_resources and import it through chrome.runtime.getURL. See Lazy loading for both rules.
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/commandsconfiguration keys before low-level bundler overrides. - Patch minimally: Change only the pieces you need, then return the configuration.
- Keep plugins Rspack-aware: Prefer Rspack-native plugins when available.
- Verify on all targets: Test
dev,start,preview, andbuildfor your browser matrix after configuration changes.
Next steps
- Learn more about extension config (
extension.config.js). - Learn more about Multi-platform builds.

