Browser preferences#

Tune browser runtime behavior for development without changing your extension source.

Get repeatable browser behavior during development (for example, homepage defaults, devtools settings, or notification behavior) without editing extension code.

Extension.js reads preferences from extension.config.* and applies them in browser launch flows where supported.

How it works#

Preferences are configured in extension.config.js (or .mjs / .cjs) under:

• browser.<target>.preferences
• commands.dev|start|preview.preferences

Command-level values can override browser defaults.

Preference capabilities#

Firefox and Gecko-based behavior#

Example configuration#

export default {
  browser: {
    firefox: {
      preferences: {
        "browser.startup.homepage": "https://developer.mozilla.org",
        "devtools.theme": "dark",
        "dom.webnotifications.enabled": false,
      },
    },
  },
};

In Firefox/Gecko flows, Extension.js writes a user.js file into the active profile (managed or explicit profile) and merges:

• internal baseline preferences required for dev/runtime behavior
• your custom preferences values (your values win on key conflicts)

If system profile mode is enabled (EXTENSION_USE_SYSTEM_PROFILE=true), no managed profile file is written.

Chromium-family behavior#

Chromium-family launches (chrome, edge, chromium, chromium-based) primarily use browser flags.

preferences can still exist in merged config objects, but Chromium launch behavior is controlled by flags/profile args, not a Firefox-style user.js preference file.

For Chromium customization, prefer:

• browserFlags
• excludeBrowserFlags
• profile / persistProfile

Dark mode defaults#

Extension.js injects dark-mode defaults unless you already define those keys:

• Chromium family: dark-mode launch flags
• Firefox/Gecko family: dark-mode preference keys (for UI + content color scheme)

Your explicit preferences/flags override these defaults.

Interface example#

export default {
  commands: {
    dev: {
      browser: "firefox",
      preferences: {
        "devtools.theme": "dark",
      },
    },
  },
};

Example with custom profile#

export default {
  browser: {
    firefox: {
      profile: "path/to/custom-profile",
      preferences: {
        "browser.startup.homepage": "https://example.com",
      },
    },
  },
};

More detailed preference references#

For a comprehensive list of available Firefox preferences, you can explore the Firefox source code where many default preferences are defined in all.js or firefox.js.

Best practices#

• Prefer browser-scoped preferences: Keep Firefox/Gecko preference keys under browser-targeted config blocks.
• Use command overrides for temporary experiments: Put short-lived preference tweaks in commands.dev.
• Keep profiles isolated: Use separate profiles for reproducible debugging.
• Use flags for Chromium tuning: Treat flags as the primary configuration surface on Chromium-family targets.

Next steps#

• Learn more about Browser flags.
• Learn more about Browser profile.