Docs
Blog
Docs
Blog
The chrome browser iconThe firefox browser iconThe edge browser icon

Browser flags

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.

How it works

Define flags in configuration:

  • browser.<target>.browserFlags
  • commands.dev|start|preview.browserFlags
  • optional excludeBrowserFlags to remove defaults or user flags (runner-dependent behavior)

Merge precedence is browser defaults -> command defaults -> CLI-selected command context.

Flag capabilities

Config key What it does
browser.<target>.browserFlags Sets default launch flags for a specific browser target.
commands.dev.browserFlags Adds or overrides flags for dev runs.
commands.start.browserFlags Adds or overrides flags for start runs.
commands.preview.browserFlags Adds or overrides flags for preview runs.
browser.<target>.excludeBrowserFlags Removes matching default or user flags for a target.
commands.<name>.excludeBrowserFlags Removes flags in a command-specific context.

Video demo soon: browser flag merge precedence

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).
    • --load-extension=... is managed by Extension.js and filtered 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.

Video demo soon: chromium vs firefox flag behavior

Supported targets and references

Browser Usage More Information
Chrome extension dev --browser=chrome Chrome Flags
Edge extension dev --browser=edge Edge Flags
Firefox extension dev --browser=firefox Firefox Flags
Chromium-based extension dev --browser=chromium-based Chromium Flags
Gecko-based extension dev --browser=gecko-based Firefox-based browsers share the same flags as Firefox.

Use binary flags when needed for engine-based targets:

  • --chromium-binary=...
  • --gecko-binary=...

Video demo soon: engine target flags with custom binaries

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

ON THIS PAGE