Docs
Blog
Docs
Blog
👤

Browser profile

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 so you can choose clean runs, reusable state, or an explicit local profile path.

How it works

Profile mode is selected in this order:

  1. Explicit profile path (if provided)
  2. Managed profile mode (default)
    • 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 directory 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.

Video demo soon: profile mode selection

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

Managed profiles are created under:

  • dist/extension-js/profiles/<browser>-profile/<...>

Persistent mode uses:

  • dist/extension-js/profiles/<browser>-profile/dev

Video demo soon: managed profile lifecycle

Configure in extension.config.*

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

You can also scope profile defaults by command:

export default {
  commands: {
    dev: {
      persistProfile: true,
    },
  },
};

CLI usage

Use an explicit profile path directly:

extension dev --browser=chrome --profile=/path/to/custom/profile

Works similarly with start and preview.

Video demo soon: cli profile override

Lifecycle notes

  • Ephemeral managed profiles are created per run.
  • Persistent managed profile (dev) is reused across runs.
  • Managed profile directories are cleaned up with best-effort retention logic (EXTENSION_TMP_PROFILE_MAX_AGE_HOURS).

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

ON THIS PAGE