Skip to main content
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 during Firefox and Gecko browser launches.

​
How it works

Configure preferences 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

Preference keyWhat it does
browser.<target>.preferencesSets default preferences for a specific browser target.
commands.dev.preferencesSets or overrides preferences for dev runs.
commands.start.preferencesSets or overrides preferences for start runs.
commands.preview.preferencesSets or overrides preferences for preview runs.

​
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 development and runtime behavior
  • your custom preferences values (your values win on key conflicts)
If you enable system profile mode (EXTENSION_USE_SYSTEM_PROFILE=true), Extension.js does not write a managed profile file.

​
Chromium-family behavior

Chromium-family launches (chrome, edge, chromium, chromium-based) primarily use browser flags. preferences can still exist in merged configuration objects. However, flags and profile options control Chromium launch behavior. Chromium does not use 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, explore the Firefox source code. Mozilla defines many defaults in all.js or firefox.js.

​
Best practices

  • Prefer browser-scoped preferences: Keep Firefox/Gecko preference keys under browser-targeted configuration 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