> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Firefox and Gecko runtime preferences setup

> Set Firefox and Gecko runtime preferences for development without editing extension source. Configure homepage, devtools, and notification defaults.

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

```js theme={null}
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.

```js theme={null}
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.

<Note>
  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.
</Note>

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

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

### Example with custom profile

```js theme={null}
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](https://searchfox.org/mozilla-central/source/). 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](/docs/browsers/browser-flags).
* Learn more about [Browser profile](/docs/browsers/browser-profile).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.