Chrome Extension Development

Chrome Extension (Manifest V3) Development

When to use

• Building a new Chrome/Edge extension from scratch
• Adding features to an existing MV3 extension
• Integrating LLM APIs into browser extensions
• Content-script DOM manipulation at page scale

Architecture (MV3 canonical layout)

my-extension/
├── manifest.json          # MV3 manifest — permissions, CSP, entry points
├── background.js          # Service worker (no DOM access, no window)
├── lib/                   # Shared logic loaded via <script> in popup/options
│   ├── providers.js       # API abstraction layer
│   └── ...
├── content/
│   ├── content.js         # Injected into pages (has DOM, no chrome.tabs)
│   └── content.css        # Scoped styles (prefix all classes!)
├── popup/                 # Toolbar popup (own HTML/CSS/JS context)
├── options/               # Full settings page (chrome.runtime.openOptionsPage)
└── icons/                 # 16/32/48/128 PNG

Key patterns

1. Manifest essentials

• "manifest_version": 3 — required for new submissions
• "permissions": ["storage", "contextMenus", "activeTab"] — storage.sync for settings
• "host_permissions": ["<all_urls>"] — needed for fetch() to arbitrary APIs from content scripts
• Content scripts: "run_at": "document_idle" (default) or "document_start" for early injection
• "web_accessible_resources" only if page needs to load extension assets

2. Provider abstraction (LLM calls from browser)

• OpenAI-compatible: POST {baseUrl}/chat/completions, Authorization: Bearer {key}, SSE streaming via data: lines
• Anthropic: POST {baseUrl}/v1/messages, headers x-api-key + anthropic-version: 2023-06-01 + anthropic-dangerous-direct-browser-access: true (required for CORS from browser)
• Google Gemini: POST {baseUrl}/v1beta/models/{model}:generateContent?key={key} (key in URL, no auth header)
• Google Translate (free engine, NOT an LLM): GET https://translate.googleapis.com/translate_a/single?client=gtx&sl=auto&tl={target}&dt=t&q={text} — ~0.2s, no API key, no model. Offer it as a provider option alongside LLMs for raw speed. Response is nested JSON [[["translated","orig",...],...]]; concatenate j[0][*][0]. Still CORS-blocked from content scripts → route through service worker. Mark the provider with needsModel: false so the options UI hides the model/key fields. See references/provider-endpoints.md § "Free translation engine".
• All three LLM types support streaming (SSE) — parse data: lines, handle [DONE] sentinel for OpenAI
• See references/provider-endpoints.md for base URLs and model lists

2b. CRITICAL: CORS — route API calls through the service worker

Content scripts run in the PAGE's origin. fetch() from a content script to an LLM API is a cross-origin request subject to CORS. Most LLM providers (OpenAI, DashScope, OpenCode Zen, Groq, DeepSeek) do NOT send Access-Control-Allow-Origin headers → "Failed to fetch" error. host_permissions in the manifest do NOT bypass CORS for content scripts — they only grant permission for fetches from background/popup/options contexts.

The fix: proxy all LLM calls through the background service worker (which IS CORS-exempt):

1. background.js: importScripts('lib/providers.js') to load the API layer
2. background.js: chrome.runtime.onConnect listener on a named port (e.g. 'ext-llm'), calls AIT.callLLM(), posts {type:'delta'|'done'|'error'} messages back
3. providers.js: detect context via location.protocol === 'chrome-extension:' — extension pages (popup/options) call directly; content scripts open a port and proxy through background
4. Streaming works over the port: background posts {type:'delta', delta, full} per SSE chunk

This is the #1 cause of "Failed to fetch" in LLM extensions. Always architect for it from the start.

3. Content script DOM manipulation

• Namespace everything: prefix all classes/attributes (ait-, myext-) to avoid page collisions
• Block detection: walk DOM tree, skip SCRIPT/STYLE/PRE/CODE/TEXTAREA/SVG, collect visible text blocks
• Visibility check pitfall (causes "no paragraphs found" on React/Next.js SPAs): do NOT use el.getClientRects().length === 0 as a "hidden element" test. Elements with display: contents (which React/Next.js apps use heavily for layout wrappers) return an EMPTY rect list even though they and their children are fully visible. A walker that treats them as hidden skips the ENTIRE subtree → zero blocks found → "nothing to translate" on an otherwise text-rich page. Instead test only getComputedStyle(el).display === 'none' || visibility === 'hidden'. Drop the getClientRects check entirely.
• Card-splitting heuristic (fixes "spotty/gappy translation" on card UIs): a naive "container has text → translate it whole" rule grabs an entire project/product card (title + author + status all in one div) as a single block. The model then mangles the numbered output and the whole card gets dropped. Fix: count meaningful child elements (meaningfulChildCount); if ≥ 2 children carry their own text, DESCEND and translate them individually instead of the container. Only treat a container as a leaf block when it has <2 meaningful children. Simple structures (sidebars, plain paragraphs) still translate as one block.
• Parallel insertion: append translation <div> inside the source element (preserves layout flow)
• Restore: track translated elements via data-* attribute, remove inserted nodes on restore
• Display modes with instant switching (original / bilingual / translation-only): users want to toggle between "show original", "original + translation below", and "translation only" — and it must switch INSTANTLY with no re-translation (no extra API calls). The pattern: on first translate, move the element's original child nodes into a wrapper <span class="ext-orig"> (style it display: contents so it never affects layout) and append the translation <div> as a sibling, so BOTH are preserved in the DOM. Then a mode is just a CSS display toggle on those two nodes (ext-orig hidden in translation-only; translation hidden in original-only). Store the mode as data-ext-mode on the element. A global applyDisplayMode(mode) walks [data-ext-translated] and flips displays — O(n) DOM, zero network. Restore unwraps: move .ext-orig children back out, remove the wrapper + translation node, clear the attributes. Key details: (a) do the wrapping ONCE and make insert idempotent (reuse the existing .ext-orig and translation <div> on re-insert) so streaming callbacks and reconciliation don't re-wrap or duplicate; (b) backward-compat wrap: applyMode must handle elements translated by an OLDER content-script version that never created the wrapper — if switching to translation-only and no .ext-orig exists, wrap the original child nodes on the fly (collect all children except the translation <div>, move them into a fresh wrapper). Without this, mode switching silently does nothing on already-translated pages and the user reports "it's still showing below".
• Applying live setting changes to tabs with STALE content scripts (triple-path pattern): after an extension reload, already-open tabs keep running the OLD injected content script — so a popup→content message for a new feature (e.g. ext:setMode) hits a listener that doesn't exist yet, and the user sees no change no matter how correct the new code is. Don't rely on the user closing/reopening tabs. Apply the change through THREE redundant paths from the popup: (1) chrome.tabs.sendMessage (works when the tab has the new script); (2) chrome.storage.sync.set + a chrome.storage.onChanged listener in the content script (works across versions, since storage API is stable); (3) chrome.scripting.executeScript({ target: {tabId}, func, args }) from the popup — injects the apply-function DIRECTLY into the tab, guaranteed to work regardless of which content-script version is loaded. Requires the "scripting" permission (plus activeTab/host permissions). Path 3 should carry a self-contained copy of the DOM logic (no dependency on page globals). Also update the in-memory settings cache in the content script's storage listener so subsequently observed SPA content uses the new mode.
• SPA support: MutationObserver on document.body with debounce (1000-1500ms) for infinite scroll

4. Batch translation (token-efficient + fast)

• Number paragraphs 1. ... N., send as single prompt, parse numbered response
• Batch size 10-12 paragraphs per request balances token efficiency vs. reliability
• On partial failure: retry missing numbers individually
• Worker-pool parallelism (critical for speed): split blocks into batches, then run N workers (N = concurrency setting, 4-6) pulling from a shared queue via Promise.all. A naive for loop with await inside is SERIAL even with a concurrency setting — the Translator's internal slot limiter only helps within a single call. The content script must spawn multiple concurrent batch calls itself.
• Defaults: batchSize 8, concurrency 5. Free-tier models may 429 — let user dial down.
• Stream + paint line-by-line (biggest perceived-speed win): do NOT await the full batch response then render. Pass an onDelta into the LLM call, buffer chunks, split on \n, and as each numbered line completes, parse it and immediately insert that one translation into the DOM (via an onLine(origIdx, text) callback). Result: first line appears in ~1s and the page fills in progressively, instead of a 5-10s blank wait then a sudden dump. Total wall-time is similar but perceived latency drops dramatically. Make insertTranslation idempotent (if element already translated, update its child node's textContent rather than appending a duplicate) so the streaming callback and the final reconciliation pass don't double-insert.
• Keep a final reconciliation pass: after streaming, re-parse the full response for any lines the stream missed, then individually retry any still-missing numbers. Three layers (stream → full-parse → per-line retry) makes translation robust to flaky free-tier output.

5. Settings persistence

• chrome.storage.sync — syncs across user's devices (8KB per item, 100KB total)
• chrome.storage.local — for large data (caches, model lists)
• Pattern: getSettings() returns Promise merging DEFAULTS + stored values
• Per-provider credential storage (users WILL ask for this): when an extension supports multiple API providers, storing a single global apiKey/baseUrl/model means switching providers wipes the previous provider's credentials. The fix: store a providerConfigs map keyed by provider ID:

  // chrome.storage.sync schema:
  // providerConfigs: {
  //   alibaba: { apiKey: '***', baseUrl: '...', model: 'qwen3.6-flash' },
  //   openai:  { apiKey: '***', baseUrl: '...', model: 'gpt-4o-mini' },
  // }
  

  Implementation: (a) getSettings() merges providerConfigs[activeProvider] over defaults; (b) on provider switch in options UI, save current field values to providerConfigs[oldProvider], then load providerConfigs[newProvider] into the form; (c) on any field change event, also write through to providerConfigs[currentProvider]; (d) legacy migration: if providerConfigs is empty but a global apiKey exists, copy it into providerConfigs[currentProvider] once and persist — so existing users don't lose their key on upgrade.

Pitfalls

• Service worker has no DOM/window — no document, no alert(), no XMLHttpRequest. Use fetch().
• Content scripts can't use chrome.tabs — message the background worker instead
• CORS: Anthropic requires the anthropic-dangerous-direct-browser-access header. Ollama needs OLLAMA_ORIGINS=* env var. LM Studio allows browser CORS by default. All other providers (OpenAI, DashScope, OpenCode Zen, Groq, DeepSeek) block browser CORS — route through service worker (see §2b).
• CSS scoping: content script CSS is global to the page. Always prefix classes. Use high z-index (2147483646+) for overlays.
• Translation-text legibility (users will call out faint output): when rendering inserted translations, default to HIGH contrast, not subtle. Users consistently report "it's too faint / hard to see". Starting point that reads well on light pages: text color a strong dark accent (e.g. #065f56 teal, not a washed-out grey-green), font-weight: 500, font-size at LEAST 1.0em (never shrink to 0.95em), a 4px left accent bar (a vertical gradient reads as more polished than flat), and a ~10% tinted background that deepens to ~16% on :hover. Provide a :hover state — it doubles as affordance and contrast check. For a "translation-only" mode, STRIP all decoration (border/background/padding/margin/color: inherit) via a [data-ext-mode="translation"] > .ext-translation rule so the text reads as the page's own native content rather than an obvious overlay.
• chrome.storage.sync limits: 8KB per key. Don't store model lists there — use local or keep in memory.
• Popup/options are separate JS contexts — they don't share globals with content scripts. Use chrome.storage or messaging.
• MV3 service workers die after 30s idle — don't rely on persistent state in background.js variables.
• "Too slow" diagnosis ladder: (1) Is it serial? → worker-pool parallelism (§4). (2) Does the page sit blank then dump all at once? → not streaming; add line-by-line paint (§4). (3) Still slow first line? → that's server-side time-to-first-token (TTFT), NOT fixable client-side. The only levers are model choice (free tiers are slow; deepseek-v4-flash-free / qwen-turbo are the fast free options; paid flash tiers are 3-5× faster) and smaller batch size (8→4 makes the first line arrive sooner at the cost of more requests). Don't burn cycles optimizing client code for a server-bound latency.
• Don't frame speed as "LLM = slow, translation API = fast" — it's a spectrum, and say so honestly. A user will (rightly) push back: commercial tools like Immersive Translate ALSO let you pick an LLM model, yet feel instant. The real speed levers, in order of impact: (a) engine/model choice — a dedicated translation engine (Google gtx) or a small fast LLM (qwen-turbo, groq llama-3.1-8b-instant) vs a flagship/reasoning model; (b) concurrency (how many parallel requests); (c) server TTFT (free tiers queue, paid tiers don't); (d) streaming paint. When comparing your extension to a polished competitor, attribute the gap to these concrete factors, not to a false LLM/non-LLM binary — and never overclaim "competitor X doesn't use LLMs" without evidence. Offer the fast engine as a choice alongside the LLM, not a replacement.
• Reasoning models are the WRONG choice for translation (and most bulk/simple tasks): models like qwen3.8-max-preview, *-reasoner, o-series, or anything with a "thinking" mode default to a huge reasoning budget (e.g. qwen3.8-max-preview defaults to xhigh effort with a 131,072-token thinking budget). Every request "thinks" before answering → catastrophic first-token latency AND the reasoning tokens are billed, draining credits/quota fast. Translation is a understand-and-substitute task that needs NO reasoning. If a user reports slowness while on a flagship reasoning model, the single highest-impact fix is switching to a small non-reasoning model (qwen-turbo, qwen-plus, qwen-flash). Rule of thumb for translation: small fast model ≈ flagship quality at ~1/30 the cost and far lower latency. Reserve reasoning models for genuinely hard multi-step work, never bulk text transforms.
• Code reload requires remove+re-add, not just refresh: After editing extension files, the 🔄 refresh button on chrome://extensions often does NOT pick up content script changes reliably. The reliable sequence: (1) Remove the extension, (2) Load unpacked again, (3) Close all tabs that had the old content script, (4) Open a fresh tab. Existing tabs retain the old injected content script even after extension reload — this is the #1 cause of "I fixed the code but the error persists" during development.
• Hermes output redaction corrupts credential-field code: The Hermes runtime redacts strings matching secret patterns (e.g. apiKey: *** in BOTH tool output display AND patchtoolnew_stringinputs. When youpatcha file with code likeapiKey: *** the tool may silently write apiKey: *** into the actual file, producing a SyntaxError. The read_fileoutput also shows***so you can't tell if the file is actually broken or just display-redacted. **Diagnosis**: runnode --check — if it reportsUnexpected token '**'the file is genuinely corrupted. **Fix**: write a Python script that builds the correct line viabase64.b64decode(...)` and writes it by line number, bypassing the redaction filter entirely. Example:

  import base64
  lines = open(f, encoding='utf-8').readlines()
  # base64 of "    apiKey: ***"
  correct = base64.b64decode('ICAgIGFwaUtleTogJCgnYXBpS2V5JykudmFsdWUudHJpbSgpLA==').decode()
  lines[89] = correct + '\n'
  open(f, 'w', encoding='utf-8').writelines(lines)
  

  Always node --check after any patch touching credential fields. This applies to ANY code with apiKey, api_key, secret, token assignment patterns.

Verification checklist

1. node --check every .js file (syntax)
2. JSON.parse the manifest (valid JSON)
3. Load unpacked at chrome://extensions with Developer mode ON
4. Check service worker console (click "Inspect views: service worker")
5. Check content script console (page DevTools → console, select extension context)
6. Test on a real page with varied DOM (news article, SPA, table-heavy page)

Support files

• references/provider-endpoints.md — LLM provider base URLs, auth patterns, model lists
• templates/manifest.json — starter MV3 manifest