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

# Browser profile management for isolated dev runs

> Manage browser state isolation during extension development with managed, persistent, or custom profile paths for Chrome and Firefox.

Control browser state isolation during development with managed, persistent, or custom profiles.

Keep browser sessions isolated or persistent based on your workflow. Extension.js launches browsers with profile-aware defaults. Choose clean runs, reusable state, or an explicit local profile path.

## How it works

Extension.js chooses the profile mode in this order:

1. Explicit `profile` path (if provided)
2. Managed profile mode (default)
   * temporary (ephemeral) by default
   * persistent when `persistProfile: true`
3. System profile mode when `EXTENSION_USE_SYSTEM_PROFILE=true`

## Profile capabilities

| Config / option                     | What it does                                                    |
| ----------------------------------- | --------------------------------------------------------------- |
| `browser.<target>.profile`          | Uses an explicit profile folder for that browser target.        |
| `commands.dev.profile`              | Uses an explicit profile only for `dev`.                        |
| `commands.start.profile`            | Uses an explicit profile only for `start`.                      |
| `commands.preview.profile`          | Uses an explicit profile only for `preview`.                    |
| `browser.<target>.persistProfile`   | Reuses managed profile state between runs for a target.         |
| `commands.<name>.persistProfile`    | Reuses managed profile state in a command-specific context.     |
| `--profile=/abs/path`               | CLI override for explicit profile path.                         |
| `EXTENSION_USE_SYSTEM_PROFILE=true` | Uses the OS/browser system profile instead of managed profiles. |

## Profile modes

| Mode                    | How to enable                                   | Typical use                                   |
| ----------------------- | ----------------------------------------------- | --------------------------------------------- |
| Managed ephemeral       | default                                         | clean runs with isolated state                |
| Managed persistent      | `persistProfile: true`                          | iterative debugging with stable browser state |
| Explicit custom profile | `profile: "/abs/path"` or `--profile=/abs/path` | reuse an existing profile                     |
| System profile          | `EXTENSION_USE_SYSTEM_PROFILE=true`             | launch with OS/browser default profile        |

Extension.js creates managed profiles under:

* `dist/extension-js/profiles/<browser>-profile/<...>`

Persistent mode uses:

* `dist/extension-js/profiles/<browser>-profile/dev`

## Configure in `extension.config.*`

```js theme={null}
export default {
  browser: {
    chrome: {
      // Use your own profile folder:
      profile: "path/to/custom/profile",
    },
    firefox: {
      // Keep a stable managed profile for repeated sessions:
      persistProfile: true,
    },
  },
};
```

You can also scope profile defaults by command:

```js theme={null}
export default {
  commands: {
    dev: {
      persistProfile: true,
    },
  },
};
```

## CLI usage

Use an explicit profile path directly:

```bash theme={null}
extension dev --browser=chrome --profile=/path/to/custom/profile
```

Works similarly with `start` and `preview`.

## Lifecycle notes

* Extension.js creates ephemeral managed profiles for each run.
* Extension.js reuses the persistent managed profile (`dev`) across runs.
* Extension.js automatically removes old managed profile folders. Set `EXTENSION_TMP_PROFILE_MAX_AGE_HOURS` to control the maximum age.

## Best practices

* **Use managed ephemeral profiles for baseline testing**: Reduces hidden state and flaky reproductions.
* **Use `persistProfile` for long-lived debug sessions**: Keep auth/session/devtools state between runs.
* **Keep custom profiles per browser family**: Avoid cross-browser contamination.
* **Use system profile mode intentionally**: Useful for reproduction, but less isolated than managed profiles.

## Next steps

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