Documentation Index
Fetch the complete documentation index at: https://extension.js.org/llms.txt
Use this file to discover all available pages before exploring further.
Use one configuration file to set browser defaults, command behavior, and bundler customization.
Share browser defaults, command options, and build settings across your team. Stop repeating CLI flags. Extension.js reads extension.config.js (or .mjs / .cjs) from your project root. It applies settings to every command and the bundler.
How it works
Add extension.config.js at your project root (same level as package.json in typical setups).
Supported file names:
extension.config.jsextension.config.mjsextension.config.cjs
Top-level keys:
| Key | Description |
|---|
browser | Browser-specific defaults keyed by browser target. |
commands | Per-command defaults (dev, start, preview, build). |
extensions | Companion extensions applied across commands (load-only). |
transpilePackages | Packages to compile before bundling (useful for monorepo/workspace setups). |
config | Hook to extend/override the generated Rspack config. |
Environment loading for configuration files
extension.config.* runs in Node and should read values from process.env.*.
- Extension.js preloads env files before evaluating
extension.config.*.
- It first checks the project folder.
- In monorepos, if Extension.js finds no project-local
.env* file, it falls back to the nearest workspace root. The workspace root is the folder containing pnpm-workspace.yaml.
- Prefer built-in env preload over importing
dotenv in your configuration file.
Browser configuration
Need different browser defaults per target? Use browser:
export default {
browser: {
chrome: {
profile: 'path/to/profile',
preferences: {darkMode: true},
browserFlags: ['--disable-web-security'],
excludeBrowserFlags: ['--mute-audio']
},
'chromium-based': {
chromiumBinary: '/path/to/brave-or-other-chromium-binary'
},
firefox: {
geckoBinary: '/path/to/firefox'
}
}
}
chrome, edge, firefox, chromium, chromium-based, gecko-based, firefox-based.
Common browser fields:
profile, persistProfilepreferencesbrowserFlags, excludeBrowserFlagschromiumBinary, geckoBinaryextensions (companion load-only extensions)
Browser target capabilities
| Key | What it does |
|---|
profile | Sets the browser profile path (or profile behavior) used when launching. |
persistProfile | Reuses profile data between runs. |
preferences | Applies browser preference overrides. |
browserFlags | Adds launch flags for the browser process. |
excludeBrowserFlags | Removes default launch flags you do not want. |
chromiumBinary | Uses a custom Chromium-family binary path. |
geckoBinary | Uses a custom Gecko/Firefox binary path. |
extensions | Loads companion extensions together with the main extension. |
Commands configuration
Use commands to define defaults per command:
export default {
transpilePackages: ['@workspace/ui'],
commands: {
dev: {
browser: 'chrome',
polyfill: true,
logLevel: 'info',
persistProfile: true,
browserFlags: ['--headless=new'],
extensions: {dir: './extensions'}
},
start: {
browser: 'firefox',
source: 'https://example.com'
},
preview: {
browser: 'edge',
noBrowser: false
},
build: {
browser: 'chrome',
zip: true,
zipSource: true,
zipFilename: 'my-extension.zip',
transpilePackages: ['@workspace/ui', '@workspace/icons']
}
}
}
- Extension.js merges top-level
extensions and transpilePackages into command defaults.
- Per-command values override top-level values.
- The
start command runs build then preview internally. Extension.js applies settings from commands.start, including browser-launch options like profile, browserFlags, and startingUrl. You can also put build-specific settings in commands.build.
Command capabilities (shared)
| Key | Applies to | What it does |
|---|
browser | dev, start, preview, build | Sets browser or browser-family target. |
profile | dev, start, preview | Sets browser profile path/behavior. |
persistProfile | dev, start, preview | Reuses browser profile data between runs. |
chromiumBinary | dev, start, preview | Uses a custom Chromium-family binary. |
geckoBinary | dev, start, preview | Uses a custom Gecko-family binary. |
polyfill | dev, start, build | Enables compatibility polyfill behavior where relevant. |
preferences | dev, start, preview | Applies browser preference overrides. |
browserFlags | dev, start, preview | Adds launch flags for the browser process. |
excludeBrowserFlags | dev, start, preview | Removes default launch flags you do not want. |
startingUrl | dev, start, preview | Opens a specific URL on browser launch. |
port | dev, start, preview | Sets runner/DevTools port. |
host | dev, start, preview | Sets dev server host. Use 0.0.0.0 for Docker/dev containers. |
noBrowser | dev, start, preview | Disables browser launch. |
extensions | dev, start, preview, build | Loads companion extensions (or extension list). |
install | dev, start, build | Installs missing dependencies before running. |
transpilePackages | dev, start, preview, build | Transpiles listed workspace/external packages. |
build command capabilities
| Key | What it does |
|---|
zip | Generates a packaged zip artifact. |
zipSource | Adds source bundle/archive output for review/compliance workflows. |
zipFilename | Sets a custom zip output filename. |
silent | Reduces build log output. |
dev command capabilities
| Key | What it does |
|---|
noOpen | Runs dev server without auto-opening browser. |
source | Enables source-inspection flow from a remote source URL. |
watchSource | Re-runs source inspection when watched updates occur. |
sourceFormat | Sets source output format (pretty, json, ndjson). |
sourceSummary | Emits compact source summary output. |
sourceMeta | Includes page metadata in source output. |
sourceProbe | Probes source output with specific CSS selectors. |
sourceTree | Controls compact extension tree output. |
sourceConsole | Includes console summary in source output. |
sourceDom | Includes DOM snapshots/diffs in source output. |
sourceMaxBytes | Caps source output payload size. |
sourceRedact | Controls source redaction strategy. |
sourceIncludeShadow | Controls Shadow DOM inclusion strategy. |
sourceDiff | Includes diff metadata on source watch updates. |
Logging capabilities
| Key | Applies to | What it does |
|---|
logs | dev, start, preview | Sets minimum log level (off to all). |
logContext | dev, start, preview | Filters logs by context (background, content, etc.). |
logFormat | dev, start, preview | Sets output format (pretty, json, ndjson). |
logUrl | dev, start, preview | Filters logs by URL pattern. |
logTab | dev, start, preview | Filters logs by tab ID. |
Rspack configuration
Need advanced bundler customization? Use config to patch the generated Rspack configuration:
export default {
config: (config) => {
config.module.rules.push({
test: /\.mdx$/,
use: ['babel-loader', '@mdx-js/loader']
})
return config
}
}
config may also be an object, which Extension.js merges on top of the generated config.
Full sample
export default {
browser: {
chrome: {browser: 'chrome', profile: 'default'},
firefox: {browser: 'firefox', persistProfile: true},
'chromium-based': {
browser: 'chromium-based',
chromiumBinary:
'/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'
}
},
commands: {
dev: {
browser: 'chrome',
polyfill: true,
host: '0.0.0.0',
extensions: {dir: './extensions'}
},
start: {browser: 'edge'},
preview: {browser: 'firefox'},
build: {
zipFilename: 'extension.zip',
zip: true,
zipSource: true
}
},
extensions: {dir: './extensions'},
transpilePackages: ['@workspace/ui'],
config: (config) => config
}
Best practices
- Keep browser-specific values in
browser: Keep command definitions focused on workflow, not browser internals.
- Use top-level defaults intentionally: Put shared
extensions / transpilePackages at root; override only where needed.
- Prefer
chromiumBinary/geckoBinary names: They align with current command and type surface.
- Keep
config hook minimal: Add only what first-class Extension.js options do not cover.
Next steps
