#Browser Launch

Addfox can automatically launch the browser and load the extension during development for improved efficiency.

#Quick Start

Run the dev command:

pnpm

npm

yarn

bun

pnpm dev

npm run dev

yarn dev

bun run dev

On first start, the dev server will automatically:

1. Build the extension
2. Launch the browser
3. Load the development extension

#Using Scripts (Recommended)

Configure scripts in package.json for cleaner browser launch commands:

{
  "scripts": {
    "dev": "addfox dev",
    "dev:chrome": "addfox dev -b chrome",
    "dev:edge": "addfox dev -b edge",
    "dev:brave": "addfox dev -b brave",
    "dev:firefox": "addfox dev -b firefox"
  }
}

Then use directly:

pnpm

npm

yarn

bun

# Chrome (default)
pnpm dev

# Other browsers
pnpm dev:edge
pnpm dev:firefox

# Chrome (default)
npm run dev

# Other browsers
npm run dev:edge
npm run dev:firefox

# Chrome (default)
yarn dev

# Other browsers
yarn dev:edge
yarn dev:firefox

# Chrome (default)
bun run dev

# Other browsers
bun run dev:edge
bun run dev:firefox

#Chromium-based Browsers

Addfox natively supports the following Chromium-based browsers:

#Launch via CLI Directly

If not using scripts, you can also launch directly via CLI:

pnpm

npm

yarn

bun

# Chrome (default)
pnpm addfox dev

# Other browsers
pnpm addfox dev -b edge
pnpm addfox dev -b brave
pnpm addfox dev -b vivaldi

# Chrome (default)
npx addfox dev

# Other browsers
npx addfox dev -b edge
npx addfox dev -b brave
npx addfox dev -b vivaldi

# Chrome (default)
yarn addfox dev

# Other browsers
yarn addfox dev -b edge
yarn addfox dev -b brave
yarn addfox dev -b vivaldi

# Chrome (default)
bunx addfox dev

# Other browsers
bunx addfox dev -b edge
bunx addfox dev -b brave
bunx addfox dev -b vivaldi

#Chromium Browser Configuration

If the browser is not in the default location, specify the browser object in config:

// addfox.config.ts
export default defineConfig({
  browser: {
    chrome: { path: "/path/to/chrome" },
    edge: { path: "/path/to/edge" },
    brave: { path: "/path/to/brave" },
  },
});

Each browser entry supports:

• path — browser executable path
• profile — custom user-data (profile) directory; relative paths resolve from the project root (default: <outputRoot>/cache/browser-profile/<name>-user-data)
• keepBrowserProfile — keep this browser's profile between launches, overriding the top-level keepBrowserProfile

// Before (deprecated)
export default defineConfig({
  browserPath: { chrome: "/path/to/chrome" },
});

// After
export default defineConfig({
  browser: { chrome: { path: "/path/to/chrome" } },
});

#Platform Examples

macOS:

export default defineConfig({
  browser: {
    chrome: { path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" },
    edge: { path: "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" },
  },
});

Windows:

export default defineConfig({
  browser: {
    chrome: { path: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" },
    edge: { path: "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe" },
  },
});

Linux:

export default defineConfig({
  browser: {
    chrome: { path: "/usr/bin/google-chrome" },
    chromium: { path: "/usr/bin/chromium-browser" },
  },
});

#Chromium User Data Cache

By default, a new user data directory is used on each start. To preserve data (e.g., stay logged in), add to package.json:

{
  "scripts": {
    "dev:keep-profile": "addfox dev -b chrome --keep-browser-profile",
    "dev:edge:keep-profile": "addfox dev -b edge --keep-browser-profile"
  }
}

Or run directly via CLI:

pnpm

npm

yarn

bun

pnpm addfox dev --keep-browser-profile

npx addfox dev --keep-browser-profile

yarn addfox dev --keep-browser-profile

bunx addfox dev --keep-browser-profile

Or enable in config:

export default defineConfig({
  keepBrowserProfile: true,
});

Or per browser (overrides the top-level keepBrowserProfile):

export default defineConfig({
  browser: {
    chrome: { keepBrowserProfile: true },
  },
});

User data is saved in .addfox/cache/browser-profile/<name>-user-data.

#Firefox

Firefox dev mode uses the web-ext tool to manage extension lifecycle.

#Launch Firefox

Using the configured script:

pnpm dev:firefox

Or run directly via CLI:

pnpm

npm

yarn

bun

pnpm addfox dev -b firefox

npx addfox dev -b firefox

yarn addfox dev -b firefox

bunx addfox dev -b firefox

#Firefox Features

• Extension reload is handled by web-ext, not Addfox's WebSocket
• Automatically opens Firefox and loads the extension
• Supports auto-reload on file changes

#Firefox Path Configuration

export default defineConfig({
  browser: {
    firefox: { path: "/Applications/Firefox.app/Contents/MacOS/firefox" },
  },
});

#Debugging Tips

#View Service Worker

1. Open chrome://extensions/
2. Find the extension under development
3. Click "Service Worker" to view background script console

#View Content Script

1. Right-click on the webpage → Inspect
2. Switch to Console panel
3. Select the extension's context

#Use Error Monitor

Add debug scripts to package.json:

{
  "scripts": {
    "dev:debug": "addfox dev --debug",
    "dev:firefox:debug": "addfox dev -b firefox --debug"
  }
}

Then run:

pnpm dev:debug

Or enable directly via CLI:

pnpm

npm

yarn

bun

pnpm addfox dev --debug

npx addfox dev --debug

yarn addfox dev --debug

bunx addfox dev --debug

#Related Configuration

• browser - Browser configuration (path, profile, keepBrowserProfile)
• keepBrowserProfile / buildCache - Cache configuration
• hotReload - Hot reload configuration
• debug - Error monitoring configuration