#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

#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.

#Supported targets and references

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

• Learn more about Browser Preferences.
• Learn more about Browser Profile.