👤

    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 / optionWhat it does
    browser.<target>.profileUses an explicit profile directory 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

    Managed profiles are created 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 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.

    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