Browser profile management for isolated dev runs

​

How it works

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

​

Profile modes

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

• 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,
    },
  },
};

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

​

CLI usage

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

​

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.
• Learn more about Browser flags.