Skip to main content
Control browser launch behavior for debugging, automation, and runtime experiments. Tune browser launch behavior without changing extension source code. Extension.js merges browser flags from your extension.config.* and applies them in dev, preview, and start flows.

​
Template examples

​
new-browser-flags

new-browser-flags template screenshot See browser flags in action with a new-tab extension that configures launch behavior. 
npx extension@latest create my-extension --template=new-browser-flags
Repository: extension-js/examples/new-browser-flags

​
How it works

Configure flags in extension.config.*:
  • browser.<target>.browserFlags
  • commands.dev|start|preview.browserFlags
  • optional excludeBrowserFlags to remove defaults or user flags (runner-dependent behavior)
Override order: browser defaults → command defaults → CLI-selected command context.

​
Flag capabilities

Config keyWhat it does
browser.<target>.browserFlagsSets default launch flags for a specific browser target.
commands.dev.browserFlagsAdds or overrides flags for dev runs.
commands.start.browserFlagsAdds or overrides flags for start runs.
commands.preview.browserFlagsAdds or overrides flags for preview runs.
browser.<target>.excludeBrowserFlagsRemoves matching default or user flags for a target.
commands.<name>.excludeBrowserFlagsRemoves flags in a command-specific context.

​
Example configuration

export default {
  browser: {
    chrome: {
      browserFlags: ['--disable-web-security', '--auto-open-devtools-for-tabs'],
      excludeBrowserFlags: ['--mute-audio']
    },
    firefox: {
      browserFlags: ['--devtools', '--new-instance'],
      excludeBrowserFlags: ['--devtools']
    }
  }
}

​
Chromium vs Firefox behavior

  • Chromium family (chrome, edge, chromium, chromium-based)
    • Starts from an internal default flag set, then appends your browserFlags.
    • excludeBrowserFlags removes matching default flags (exact-match filtering).
    • Extension.js manages --load-extension=... and filters it out from user-provided flags.
  • Firefox/Gecko family (firefox, gecko-based / firefox-based)
    • Uses user-provided browserFlags (no large default flag bundle like Chromium).
    • excludeBrowserFlags removes user flags by prefix matching.

​
Default Chromium flags

Extension.js applies these flags automatically when launching Chromium-family browsers. Use excludeBrowserFlags to remove any you do not need.
FlagPurpose
--no-first-runDisable first run experience
--disable-client-side-phishing-detectionDisable phishing detection
--disable-syncDisable sync to avoid account prompts
--disable-component-extensions-with-background-pagesDisable built-in extensions not affected by --disable-extensions
--disable-default-appsDisable installation of default apps
--disable-features=InterestFeedContentSuggestionsDisable Discover feed on new tab page (NTP)
--disable-features=TranslateDisable Chrome translation
--hide-scrollbarsHide scrollbars from screenshots
--mute-audioMute any audio
--no-default-browser-checkDisable default browser check prompt
--ash-no-nudgesAvoid user education nudges
--disable-search-engine-choice-screenDisable search engine choice screen
--disable-features=MediaRouteDisable Chrome Media Router background networking
--use-mock-keychainUse mock keychain on Mac to prevent blocking dialogs
--disable-background-networkingDisable background network services
--disable-breakpadDisable crashdump collection
--disable-component-updateDisable component updates
--disable-domain-reliabilityDisable domain reliability monitoring
--no-pingsDisable hyperlink auditing pings
--enable-features=SidePanelUpdatesEnsure side panel is visible
--disable-features=DisableLoadExtensionCommandLineSwitchAllow --load-extension at the command line
--enable-unsafe-extension-debuggingAllow Chrome DevTools Protocol (CDP) extension management (Chrome 126+)
In Docker, continuous integration (CI), or containerized environments Extension.js also adds --no-sandbox and --disable-setuid-sandbox automatically.

​
Supported targets and references

BrowserUsageMore Information
Chromeextension dev --browser=chromeChrome Flags
Edgeextension dev --browser=edgeEdge Flags
Firefoxextension dev --browser=firefoxFirefox Flags
Chromium-basedextension dev --browser=chromium-basedChromium Flags
Gecko-basedextension dev --browser=gecko-basedFirefox-based browsers share the same flags as Firefox.
Use binary flags when needed for engine-based targets:
  • --chromium-binary=...
  • --gecko-binary=...

​
Best practices

  • Add only necessary flags: Minimize long flag lists to reduce flaky or non-portable setups.
  • Prefer excludeBrowserFlags over replacing defaults: Remove only what conflicts with your workflow.
  • Do not pass --load-extension manually: Extension.js manages extension loading flags internally.
  • Validate per browser family: A flag working in Chromium may be invalid or ignored in Firefox.

​
Next steps