Extension Installation & Setup¶

Prerequisites¶

Node.js: 18+ (recommend 20 LTS)
npm: 9+
Git: Latest version
Chrome/Firefox: Latest version
WXT CLI: Extension build tool

Installation¶

1. Clone Repository¶

cd certana
cd browser

2. Install Dependencies¶

npm install

3. Environment Setup¶

Create .env file:

VITE_API_URL=http://localhost:8000/v1
VITE_ENV=development

Development¶

Start Development Mode¶

# Watch and rebuild
npm run dev

# Opens in default browser
# For Chrome: Check chrome://extensions
# For Firefox: Check about:debugging

Project Structure¶

browser/
├── src/
│   ├── entrypoints/              # Entry points
│   │   ├── background.ts         # Service worker
│   │   ├── content.ts            # Content script
│   │   └── popup/                # Popup UI
│   │       ├── Popup.vue
│   │       ├── views/
│   │       ├── main.ts
│   │       └── App.vue
│   │
│   ├── components/               # Shared Vue components
│   │   ├── ImageVerifier.vue
│   │   ├── ResultDisplay.vue
│   │   ├── SettingsForm.vue
│   │   └── ...
│   │
│   ├── api-service.ts            # API client
│   ├── storage-service.ts        # Browser storage
│   ├── types.ts                  # TypeScript types
│   └── styles.css                # Global styles
│
├── public/                       # Static assets
│   └── icon/                     # Extension icons
│
├── wxt.config.ts                 # WXT configuration
├── manifest.json                 # Extension manifest (v3)
├── tsconfig.json
├── package.json
└── .env                          # Environment variables

Building¶

Development Build¶

npm run dev

Creates unpackaged extension in .output/chrome and .output/firefox.

Production Build¶

npm run build

Optimized build for distribution.

Create Distribution Package¶

# Chrome
npm run zip

# Firefox
npm run zip:firefox

Creates .crx or .xpi files in .output/zip/.

Loading Extension Locally¶

Chrome¶

Open chrome://extensions/
Enable "Developer mode" (top right)
Click "Load unpacked"
Select .output/chrome directory
Extension appears in toolbar

Firefox¶

Open about:debugging
Click "This Firefox"
Click "Load Temporary Add-on..."
Select .output/firefox/manifest.json
Extension appears in toolbar

Development Commands¶

# Watch mode with hot reload
npm run dev

# Development server
npm run dev:firefox

# Build for distribution
npm run build

# Build for specific browser
npm run build:firefox

# Create distribution packages
npm run zip
npm run zip:firefox

# Type checking
npm run compile

# View compiled Vue templates
vue-tsc --noEmit

Configuration¶

WXT Config (wxt.config.ts)¶

import { defineConfig } from 'wxt';

export default defineConfig({
  modules: ['@wxt-dev/module-vue'],
  manifest: {
    name: 'Certana',
    version: '1.0.0',
    permissions: ['storage', 'contextMenus'],
    host_permissions: ['<all_urls>'],
  },
});

Manifest v3¶

The extension uses Manifest v3 (required for modern browsers):

{
  "manifest_version": 3,
  "name": "Certana",
  "version": "1.0.0",
  "permissions": ["storage", "contextMenus", "activeTab"],
  "host_permissions": ["<all_urls>"],
  "background": {
    "service_worker": "src/entrypoints/background.ts"
  },
  "action": {
    "default_popup": "src/entrypoints/popup/index.html"
  },
  "context_menus": [
    {
      "id": "verify-image",
      "title": "Verify with Certana",
      "contexts": ["image"]
    }
  ]
}

Testing¶

Component Tests¶

# Install testing libraries
npm install --save-dev vitest @vue/test-utils

# Run tests
npm test

# Watch mode
npm test -- --watch

# Coverage
npm test -- --coverage

Manual Testing¶

# Checklist:
- [ ] Right-click on image
- [ ] Select "Verify with Certana"
- [ ] Popup opens with image preview
- [ ] Enter API key in settings
- [ ] Click verify
- [ ] Results display correctly
- [ ] History saves
- [ ] Dark mode toggle works

Debugging¶

View Logs¶

Background Script (Service Worker)¶

# Chrome
1. chrome://extensions/
2. Find Certana
3. Click "Service Worker" link
4. DevTools open

# Firefox
1. about:debugging
2. Click extension name
3. Click "Inspect" button

# Chrome
1. Right-click extension icon
2. Select "Inspect popup"
3. DevTools open for popup context

# Firefox
1. Right-click extension icon
2. Select "Inspect Popup"
3. DevTools open

Content Script¶

# Chrome
1. Right-click on webpage
2. Select "Inspect" on image
3. Go to Console tab
4. Messages from content script appear

# Firefox
1. right-click on webpage
2. Select "Inspect"
3. Console tab shows messages

Console Logging¶

// In popup
console.log('Popup message:', data);

// In content script
console.log('Content script:', data);

// In background
console.log('Background:', data);

Storage Inspection¶

Chrome¶

1. chrome://extensions/
2. Find Certana
3. Scroll down → inspect views
4. Application tab → Storage

Firefox¶

1. about:debugging
2. Click extension
3. Inspect background script
4. Storage tab

Reload Extension¶

// Auto-reload during development
npm run dev  # Uses WXT's hot reload

// Manual reload
// Chrome: chrome://extensions/ → click reload icon
// Firefox: about:debugging → click reload icon

Environment Variables¶

Development (.env)¶

VITE_API_URL=http://localhost:8000/v1
VITE_ENV=development

Production (.env.production)¶

VITE_API_URL=https://api.yourdomain.com/v1
VITE_ENV=production

Troubleshooting¶

Extension Not Appearing¶

# 1. Check build succeeded
npm run build

# 2. Reload extension
# Chrome: chrome://extensions/ → reload
# Firefox: about:debugging → reload

# 3. Check for errors
# Chrome: Developer Tools console
# Firefox: Browser console (Ctrl+Shift+K)

CORS Errors¶

Access to XMLHttpRequest blocked by CORS policy

Solution: Ensure backend has correct CORS configuration:

# backend/src/main.py
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000", "moz-extension://..."],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Storage Quota Issues¶

# Check current storage usage
chrome.storage.sync.getBytesInUse(null, function(bytes) {
  console.log(bytes);
});

# Max 100KB for sync, 10MB for local
# Solution: Use compression or local storage instead

Manifest Errors¶

Manifest parsing error: ...

Solution: Validate manifest.json:

# Use online validator
# https://www.jsonlint.com/

# Or validate locally
node -e "console.log(JSON.parse(require('fs').readFileSync('manifest.json')))"

Publishing¶

Chrome Web Store¶

Create developer account
Pay $5 one-time fee
Upload ZIP package
Fill in store listing
Submit for review

Firefox Add-ons¶

Create developer account
Upload XPI package
Fill in store listing
Submit for review

See Deployment Guide for details.

Extension Installation & Setup¶

Prerequisites¶

Installation¶

1. Clone Repository¶

2. Install Dependencies¶

3. Environment Setup¶

Development¶

Start Development Mode¶

Project Structure¶

Building¶

Development Build¶

Production Build¶

Create Distribution Package¶

Loading Extension Locally¶

Chrome¶

Firefox¶

Development Commands¶

Configuration¶

WXT Config (wxt.config.ts)¶

Manifest v3¶

Testing¶

Component Tests¶

Manual Testing¶

Debugging¶

View Logs¶

Background Script (Service Worker)¶

Popup Script¶

Content Script¶

Console Logging¶

Storage Inspection¶

Chrome¶

Firefox¶

Reload Extension¶

Environment Variables¶

Development (.env)¶

Production (.env.production)¶

Troubleshooting¶

Extension Not Appearing¶

CORS Errors¶

Storage Quota Issues¶

Manifest Errors¶

Publishing¶

Chrome Web Store¶

Firefox Add-ons¶

Next Steps¶