Skip to main content
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 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 config objects. However, flags and profile options control Chromium launch behavior, 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, 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 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