Timequity Vibe Coder Browser Extension

Browser Extension Development with WXT

Quick Start

# Create new extension
npx wxt@latest init my-extension
cd my-extension

# Development (Chrome)
npm run dev

# Development (Firefox)
npm run dev:firefox

# Build for production
npm run build

# Create ZIP for store submission
npm run zip

Project Structure

my-extension/
├── wxt.config.ts           # WXT configuration
├── entrypoints/
│   ├── background.ts       # Service worker
│   ├── content.ts          # Content script
│   ├── popup/
│   │   ├── index.html
│   │   ├── main.tsx
│   │   └── App.tsx
│   └── options/
│       ├── index.html
│       └── main.tsx
├── components/             # Shared React components
├── assets/
│   └── icon.png           # Auto-generates all sizes
├── public/                 # Static files
├── package.json
└── tsconfig.json

Key difference from manual setup: No manifest.json — WXT generates it automatically from entrypoints and config.

WXT Configuration

// wxt.config.ts
import { defineConfig } from 'wxt';

export default defineConfig({
  modules: ['@wxt-dev/module-react'],
  manifest: {
    name: 'My Extension',
    description: 'A browser extension built with WXT',
    permissions: ['storage', 'activeTab'],
    host_permissions: ['https://*.example.com/*'],
  },
});

Background Script (Service Worker)

// entrypoints/background.ts
export default defineBackground(() => {
  console.log('Extension installed', { id: browser.runtime.id });

  // Listen for messages
  browser.runtime.onMessage.addListener((message, sender) => {
    if (message.type === 'GET_DATA') {
      return fetchData(); // Return promise for async response
    }
  });

  // Context menu
  browser.contextMenus.create({
    id: 'my-action',
    title: 'Do Something',
    contexts: ['selection'],
  });

  browser.contextMenus.onClicked.addListener((info, tab) => {
    if (info.menuItemId === 'my-action') {
      console.log('Selected:', info.selectionText);
    }
  });
});

Content Script

// entrypoints/content.ts
export default defineContentScript({
  matches: ['https://*.example.com/*'],
  main() {
    console.log('Content script loaded');

    // DOM manipulation
    const button = document.createElement('button');
    button.textContent = 'My Extension';
    button.onclick = () => {
      browser.runtime.sendMessage({ type: 'BUTTON_CLICKED' });
    };
    document.body.appendChild(button);

    // Listen for messages from background
    browser.runtime.onMessage.addListener((message) => {
      if (message.type === 'HIGHLIGHT') {
        document.body.style.backgroundColor = 'yellow';
      }
    });
  },
});

Content Script with UI (React)

// entrypoints/content.tsx
import ReactDOM from 'react-dom/client';
import App from './App';

export default defineContentScript({
  matches: ['https://*.example.com/*'],
  cssInjectionMode: 'ui',

  main(ctx) {
    const ui = createIntegratedUi(ctx, {
      position: 'inline',
      anchor: 'body',
      onMount: (container) => {
        const root = ReactDOM.createRoot(container);
        root.render(<App />);
        return root;
      },
      onRemove: (root) => {
        root.unmount();
      },
    });
    ui.mount();
  },
});

Popup (React)

<!-- entrypoints/popup/index.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8" />
</head>
<body>
  <div id="root"></div>
  <script type="module" src="./main.tsx"></script>
</body>
</html>

// entrypoints/popup/main.tsx
import ReactDOM from 'react-dom/client';
import App from './App';
import './style.css';

ReactDOM.createRoot(document.getElementById('root')!).render(<App />);

// entrypoints/popup/App.tsx
import { useState, useEffect } from 'react';
import { storage } from 'wxt/storage';

// Type-safe storage
const enabledStorage = storage.defineItem<boolean>('sync:enabled', {
  fallback: true,
});

export default function App() {
  const [enabled, setEnabled] = useState(true);

  useEffect(() => {
    enabledStorage.getValue().then(setEnabled);
  }, []);

  const toggle = async () => {
    const newValue = !enabled;
    await enabledStorage.setValue(newValue);
    setEnabled(newValue);
  };

  const handleAction = async () => {
    const [tab] = await browser.tabs.query({ active: true, currentWindow: true });
    if (tab.id) {
      browser.tabs.sendMessage(tab.id, { type: 'HIGHLIGHT' });
    }
  };

  return (
    <div className="p-4 w-64">
      <h1 className="text-lg font-bold mb-4">My Extension</h1>
      <label className="flex items-center gap-2 mb-4">
        <input type="checkbox" checked={enabled} />
        Enabled
      </label>
      <button
       
        className="w-full bg-blue-500 text-white py-2 rounded"
      >
        Do Something
      </button>
    </div>
  );
}

Type-Safe Storage (WXT)

// utils/storage.ts
import { storage } from 'wxt/storage';

// Define typed storage items
export const settings = storage.defineItem<{
  enabled: boolean;
  theme: 'light' | 'dark';
  apiKey?: string;
}>('sync:settings', {
  fallback: {
    enabled: true,
    theme: 'light',
  },
});

// Usage
const current = await settings.getValue();
await settings.setValue({ ...current, theme: 'dark' });

// Watch for changes
settings.watch((newValue) => {
  console.log('Settings changed:', newValue);
});

Message Passing

// Define message types
interface Messages {
  getData: { query: string };
  highlight: { color: string };
}

// Background
browser.runtime.onMessage.addListener((message: Messages[keyof Messages]) => {
  // Handle messages
});

// Content/Popup → Background
const response = await browser.runtime.sendMessage({ type: 'getData', query: 'test' });

// Background → Content
await browser.tabs.sendMessage(tabId, { type: 'highlight', color: 'yellow' });

Permissions

// wxt.config.ts
export default defineConfig({
  manifest: {
    // Required permissions (always active)
    permissions: ['storage', 'activeTab'],

    // Optional permissions (request at runtime)
    optional_permissions: ['tabs', 'history'],

    // Host permissions
    host_permissions: ['https://*.example.com/*'],
    optional_host_permissions: ['https://*/*'],
  },
});

// Request optional permission
const granted = await browser.permissions.request({
  permissions: ['tabs'],
  origins: ['https://other-site.com/*'],
});

Cross-Browser Support

WXT handles browser differences automatically:

// Use `browser` namespace (works in all browsers)
browser.storage.sync.get(['key']);
browser.runtime.sendMessage({ type: 'test' });

// WXT polyfills Chrome's callback-based APIs to Promises
const tabs = await browser.tabs.query({ active: true });

Build for specific browser:

npm run build           # Chrome (default)
npm run build:firefox   # Firefox
npm run build:safari    # Safari
npm run build:edge      # Edge

Testing

Unit Tests (Vitest)

// tests/storage.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { fakeBrowser } from 'wxt/testing';

describe('Settings storage', () => {
  beforeEach(() => {
    fakeBrowser.reset();
  });

  it('saves and loads settings', async () => {
    const { settings } = await import('../utils/storage');

    await settings.setValue({ enabled: false, theme: 'dark' });
    const result = await settings.getValue();

    expect(result.enabled).toBe(false);
    expect(result.theme).toBe('dark');
  });
});

E2E Tests (Playwright)

import { test, expect } from '@playwright/test';

test('popup opens and toggles', async ({ page, context }) => {
  // Load extension
  const extensionId = // ... get from context

  await page.goto(`chrome-extension://${extensionId}/popup.html`);

  const checkbox = page.getByRole('checkbox');
  await expect(checkbox).toBeChecked();

  await checkbox.click();
  await expect(checkbox).not.toBeChecked();
});

Common Patterns

Inject CSS

// entrypoints/content.ts
export default defineContentScript({
  matches: ['https://*.example.com/*'],
  css: ['./styles.css'], // Auto-injected
  main() {
    // ...
  },
});

Run at Document Start

export default defineContentScript({
  matches: ['*://*/*'],
  runAt: 'document_start', // Before page loads
  main() {
    // Block/modify requests early
  },
});

Alarms (Scheduled Tasks)

// entrypoints/background.ts
export default defineBackground(() => {
  browser.alarms.create('sync', { periodInMinutes: 30 });

  browser.alarms.onAlarm.addListener((alarm) => {
    if (alarm.name === 'sync') {
      syncData();
    }
  });
});

Publishing

Chrome Web Store

npm run zip              # Creates .output/my-extension-x.x.x-chrome.zip
# Upload to Chrome Web Store Developer Dashboard

Required justifications for permissions:

Warning: Broad host permissions (<all_urls>) trigger in-depth review (1-2 weeks vs days). If you only need specific sites, list them explicitly.

Store description template:

Short tagline. Clear value proposition.

How it works:
Brief explanation of the mechanism.

Features:
• Feature 1 — short description
• Feature 2 — short description
• Feature 3 — short description

Privacy-first:
• No tracking
• No accounts
• All data stored locally

Call to action.

Firefox Add-ons

npm run zip:firefox      # Creates .output/my-extension-x.x.x-firefox.zip
# Also creates .output/my-extension-x.x.x-sources.zip (required for review)
# Upload to Firefox Add-ons Developer Hub

CRITICAL: Firefox Manifest Requirements (2024+)

Firefox requires browser_specific_settings.gecko.data_collection_permissions for all new extensions:

// wxt.config.ts
export default defineConfig({
  manifest: {
    // ... other config
    browser_specific_settings: {
      gecko: {
        id: 'your-extension@your-domain.com',
        strict_min_version: '142.0', // Required for data_collection_permissions
        data_collection_permissions: {
          // For extensions that DON'T collect data:
          required: ['none'],

          // For extensions that DO collect data, specify types:
          // required: ['browsingActivity', 'websiteContent'],
          // optional: ['locationInfo'],
        },
      },
    },
  },
});

Valid data_collection_permissions values:

• 'none' — extension doesn't collect any data
• 'locationInfo' — physical location
• 'healthInfo' — health data
• 'financialAndPaymentInfo' — payment info
• 'authenticationInfo' — login credentials
• 'personalCommunications' — messages, emails
• 'browsingActivity' — browsing history
• 'websiteContent' — page content
• 'websiteActivity' — clicks, interactions
• 'searchTerms' — search queries
• 'bookmarksInfo' — bookmarks
• 'personallyIdentifyingInfo' — PII

Firefox submission notes template:

Version notes:
Initial release of [Extension Name] - [brief description].

Notes for reviewer:
- No account required to test
- To test:
  1. Install extension
  2. [Step by step testing instructions]
- No external services or APIs used
- All data stored locally via browser.storage

Edge Add-ons

# Use the same Chrome zip - Edge is Chromium-based
npm run zip              # Creates .output/my-extension-x.x.x-chrome.zip
# Upload to Edge Add-ons Developer Dashboard

Naming Convention for ZIPs

# Rename for clarity
mv .output/my-extension-1.0.0-chrome.zip ./my-extension-v1.0.0-chrome.zip
mv .output/my-extension-1.0.0-firefox.zip ./my-extension-v1.0.0-firefox.zip

Security Checklist

• Minimal permissions (request only what's needed)
• No eval() or inline scripts
• Validate all external data
• Use HTTPS only
• No API keys in source code
• Input sanitization in content scripts
• pre-commit hooks with gitleaks

Resources

• WXT Documentation
• Chrome Extensions Docs
• Firefox Add-ons Docs

Converted and distributed by TomeVault — claim your Tome and manage your conversions.