> ## 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.

<AvatarBrowsers browsers={["firefox", "gecko"]} />

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 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`) 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

```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 tuning**: Treat flags as the primary configuration surface on Chromium-family targets.

## Next steps

* Learn more about [Browser flags](/docs/browsers/browser-flags).
* Learn more about [Browser profile](/docs/browsers/browser-profile).