🦄 Features

• Build for any browser: Chrome, Firefox, Edge, Opera, Brave
• Component architecture: seven contexts (background / popup / options / sidepanel / content / pages / offscreen) each with view + styles + script
• One-line bootstrap per context with cross-browser API wrapper
• Cross-context auth sync: sign-in in one tab is reflected in all open contexts (no chrome.storage needed)
• Auto-translation to 16 languages via Claude CLI on every build
• Four-layer test framework: build / background / view / boot — real Chromium, real MV3 service worker, real consumer extensions
• Multi-browser packaging + auto-publish to Chrome / Firefox / Edge stores from one command
• Theme system: Bootstrap 5 + Classy (custom design system), or roll your own
• SCSS load paths: @use 'browser-extension-manager' / @use 'theme' Just Work — no relative-path hell

🚀 Getting started

1. Create a repo from the Ultimate Browser Extension template (or npm i browser-extension-manager in an existing project).
2. Clone the repo to your local machine.
3. Set up + run:

   npm install
   npx bxm setup
   npm start

4. Open Chrome and navigate to chrome://extensions.
5. Enable Developer mode.
6. Click Load unpacked and select the packaged/chromium/raw folder in your project.
7. Your extension is loaded and live-reloads on source changes.

📦 Sync with the template

Run npx bxm setup again to pull the latest framework defaults. Files you've edited are preserved; only missing or framework-owned files update.

🧪 Testing

BXM ships a built-in four-layer test framework. Write tests under test/<layer>/*.test.js and run with:

npx bxm test                   # all layers
npx bxm test --layer build     # build layer only (plain Node, fast)
npx bxm test --layer boot      # real-Chromium end-to-end test

Test files use Jest-compatible matchers:

// test/build/manifest.test.js
const Manager = require('browser-extension-manager/build');

module.exports = {
  layer: 'build',
  description: 'manifest is valid MV3',
  run: (ctx) => {
    const m = Manager.getManifest();
    ctx.expect(m.manifest_version).toBe(3);
    ctx.expect(m.permissions).toContain('storage');
  },
};

Full guide: docs/test-framework.md. End-to-end "did my packaged extension actually boot in Chrome?" tests: docs/test-boot-layer.md.

🌐 Auto-translation

When you run npm run build, BXM auto-translates src/_locales/en/messages.json to 16 languages via Claude CLI:

zh, es, hi, ar, pt, ru, ja, de, fr, ko, ur, id, bn, tl, vi, it

Only missing translations are generated — existing translations are preserved. Full guide: docs/translations.md.

🌎 Publishing your extension

Manual upload

npm run build

Upload the .zip files under packaged/<browser>/ to each browser's extension store.

Automatic publishing

BXM_IS_PUBLISH=true npm run build

Add store credentials to your .env:

# Chrome Web Store
CHROME_EXTENSION_ID="..."
CHROME_CLIENT_ID="..."
CHROME_CLIENT_SECRET="..."
CHROME_REFRESH_TOKEN="..."

# Firefox Add-ons
FIREFOX_EXTENSION_ID="..."
FIREFOX_API_KEY="..."
FIREFOX_API_SECRET="..."

# Microsoft Edge Add-ons
EDGE_PRODUCT_ID="..."
EDGE_CLIENT_ID="..."
EDGE_API_KEY="..."

Only stores with configured credentials get published to. Full guide: docs/publishing.md.

🔐 Authentication

BXM provides built-in cross-context authentication that syncs across all extension contexts (popup, options, sidepanel, pages, background) without using chrome.storage.

Background.js is the source of truth. Auth syncs via messaging — sign-in / sign-out events propagate across all open contexts, and new contexts handshake with background on load.

Setup

1. Add authDomain to your Firebase config in config/browser-extension-manager.json
2. Add tabs permission to src/manifest.json

Auth button classes

Add these CSS classes to HTML elements for declarative auth UI:

| Class | Action | |---|---| | .auth-signin-btn | Opens /token page on your website | | .auth-signout-btn | Signs out via Web Manager (broadcasts to all contexts) | | .auth-account-btn | Opens /account page on your website |

<button class="btn auth-signin-btn" data-wm-bind="@show !auth.user">Sign In</button>

<div data-wm-bind="@show auth.user" hidden>
  <img data-wm-bind="@attr src auth.user.photoURL">
  <span data-wm-bind="@text auth.user.displayName">User</span>
  <button class="auth-signout-btn">Sign Out</button>
</div>

Full guide: docs/auth.md.

📚 Documentation

In-depth docs for every subsystem live in docs/. See CLAUDE.md for the architecture overview + table of contents.

🧰 Sister projects

• Electron Manager (EM) — same patterns, but for Electron desktop apps
• Ultimate Jekyll Manager (UJM) — Jekyll static-site framework
• Backend Manager (BEM) — Firebase Functions backend framework