Skip to main content

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.

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.

​
Does Firefox have firefox://flags?

Firefox does not use firefox://flags the way Chromium browsers use chrome://flags or edge://flags. Firefox exposes runtime toggles through about:config (preferences) and accepts launch flags from the command line. If you searched for firefox://flags, firefox //flags, browser://flags, mozilla://flags, or about flags firefox, you are probably trying to change browser behavior during extension development. In Extension.js, do that in two places:
  • Use browserFlags for launch-time flags Extension.js passes to the browser binary.
  • Use Firefox preferences for repeatable Gecko runtime behavior that would otherwise live in about:config.
Both work for Chrome, Edge, and Firefox extension development from the same Extension.js project.

​
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 (behavior depends on whether you target Chromium or Firefox).
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+)
--silent-debugger-extension-apiSuppress the “X is debugging this browser” infobar
In Docker, continuous integration (CI), or containerized environments, Extension.js also applies --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