Skip to main content
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 / optionWhat it does
browser.<target>.profileUses an explicit profile folder for that browser target.
commands.dev.profileUses an explicit profile only for dev.
commands.start.profileUses an explicit profile only for start.
commands.preview.profileUses an explicit profile only for preview.
browser.<target>.persistProfileReuses managed profile state between runs for a target.
commands.<name>.persistProfileReuses managed profile state in a command-specific context.
--profile=/abs/pathCLI override for explicit profile path.
EXTENSION_USE_SYSTEM_PROFILE=trueUses the OS/browser system profile instead of managed profiles.

​
Profile modes

ModeHow to enableTypical use
Managed ephemeraldefaultclean runs with isolated state
Managed persistentpersistProfile: trueiterative debugging with stable browser state
Explicit custom profileprofile: "/abs/path" or --profile=/abs/pathreuse an existing profile
System profileEXTENSION_USE_SYSTEM_PROFILE=truelaunch 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.*

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

​
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