Firefox and Gecko runtime preferences setup

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 at browser launch. Firefox and Gecko targets get a user.js file. Chromium targets get a seeded Default/Preferences file.

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 key	What it does
`browser.<target>.preferences`	Sets default preferences for a specific browser target.
`commands.dev.preferences`	Sets or overrides preferences for `dev` runs.
`commands.start.preferences`	Sets or overrides preferences for `start` runs.
`commands.preview.preferences`	Sets 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) seed your preferences too, through the profile rather than a user.js file. At launch, Extension.js deep-merges your preferences object into the vendor’s master-preferences baseline. The result is written once to Default/Preferences inside the active profile. The write happens only when that file does not exist yet, so a fresh profile gets seeded and an existing profile keeps its state. Chrome and Edge each have their own baseline object, chosen by the target you run.

export default {
  browser: {
    chrome: {
      preferences: {
        download: { prompt_for_download: false },
      },
    },
  },
};

Your values win over the baseline on key conflicts, and nested objects merge key by key.

Because the write is once per profile, a persisted profile (persistProfile or keepProfileChanges) does not pick up later preference edits. Delete the profile, or run an ephemeral profile, to re-seed.

For launch behavior that Chromium controls through the command line, use flags instead:

browserFlags
excludeBrowserFlags
profile / persistProfile

For CI or harnesses that must add launch flags without touching extension.config.js, set EXTENSION_BROWSER_FLAGS (whitespace-separated, for example --headless=new). It applies to every launched browser and is appended after config browserFlags, so the environment wins when a flag repeats.

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 launch tuning: Preferences seed the profile once, so per-run behavior changes belong in flags.

Next steps

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

⌘I

Introduction

Browser extension fundamentals

Getting started

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

Firefox and Gecko runtime preferences setup

How it works

Preference capabilities

Firefox and Gecko-based behavior

Example configuration

Chromium-family behavior

Dark mode defaults

Interface example

Example with custom profile

More detailed preference references

Best practices

Next steps

​How it works

​Preference capabilities

​Firefox and Gecko-based behavior

​Example configuration

​Chromium-family behavior

​Dark mode defaults

​Interface example

​Example with custom profile

​More detailed preference references

​Best practices

​Next steps

How it works

Preference capabilities

Firefox and Gecko-based behavior

Example configuration

Chromium-family behavior

Dark mode defaults

Interface example

Example with custom profile

More detailed preference references

Best practices

Next steps