Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-backend-chrome-extension-mv3

tpl-backend-chrome-extension-mv3

Verified

Template do pack (backend/12-chrome-extension-mv3.md). Orienta o agente em APIs, servicos e arquitetura backend alinhado a esse contexto.

PROJECT: Chrome Extension Manifest V3

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: backend/12-chrome-extension-mv3.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

STACK

  • Platform: Chrome Extension Manifest V3
  • Language: TypeScript 5.x (strict)
  • UI Framework: React 19 (popup + options pages)
  • Build tool: Vite + CRXJS v2
  • Styling: Tailwind CSS v3
  • State: Zustand (popup) + chrome.storage.sync
  • Testing: Vitest + happy-dom (unit), Playwright (E2E)

PROJECT STRUCTURE

src/
├── background/
│   └── service-worker.ts     # Background service worker
├── content/
│   ├── index.ts              # Content script entry
│   └── injected.ts           # Injected script (isolated world)
├── popup/
│   ├── index.html
│   ├── App.tsx
│   └── components/
├── options/
│   ├── index.html
│   └── App.tsx
├── shared/
│   ├── messages.ts           # Message type definitions
│   ├── storage.ts            # chrome.storage wrappers
│   └── utils.ts
public/
└── icons/
manifest.json
vite.config.ts
tsconfig.json

ARCHITECTURE RULES

  1. Service worker is stateless — it can be terminated at any time; never rely on in-memory state; use chrome.storage.
  2. Content scripts are isolated — they run in the page context but cannot access page JS variables directly; use window.postMessage or injected scripts.
  3. Message passing is typed — define a discriminated union AppMessage; use chrome.runtime.sendMessage only with typed messages.
  4. Permissions are minimal — request only what is needed; do not use <all_urls> if a specific match pattern suffices.
  5. No eval / dynamic code execution — MV3 CSP blocks it; build everything at compile time.
  6. storage.sync for user preferences — storage.local for large or sensitive data.
  7. CRXJS handles HMR — never manually reload in development.

MANIFEST V3 CONFIGURATION

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "description": "Production-ready Chrome Extension",
  "permissions": [
    "storage",
    "activeTab",
    "scripting"
  ],
  "host_permissions": [
    "https://api.example.com/*"
  ],
  "background": {
    "service_worker": "src/background/service-worker.ts",
    "type": "module"
  },
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "js": ["src/content/index.ts"],
      "run_at": "document_idle"
    }
  ],
  "action": {
    "default_popup": "src/popup/index.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png",
      "128": "icons/icon128.png"
    }
  },
  "options_ui": {
    "page": "src/options/index.html",
    "open_in_tab": true
  }
}

TYPED MESSAGE PASSING

// src/shared/messages.ts
export type AppMessage =
  | { type: 'GET_PAGE_DATA' }
  | { type: 'PAGE_DATA'; payload: { title: string; url: string } }
  | { type: 'SET_BADGE'; count: number }
  | { type: 'OPEN_OPTIONS' }

// src/background/service-worker.ts
import type { AppMessage } from '../shared/messages'

// Service worker: listen for messages from popup or content
chrome.runtime.onMessage.addListener(
  (message: AppMessage, sender, sendResponse) => {
    if (message.type === 'GET_PAGE_DATA') {
      // Query active tab
      chrome.tabs.query({ active: true, currentWindow: true }, async ([tab]) => {
        if (!tab.id) return
        const results = await chrome.scripting.executeScript({
          target: { tabId: tab.id },
          func: () => ({ title: document.title, url: location.href }),
        })
        sendResponse({ type: 'PAGE_DATA', payload: results[0].result })
      })
      return true // keeps channel open for async response
    }

    if (message.type === 'SET_BADGE') {
      chrome.action.setBadgeText({ text: String(message.count) })
      chrome.action.setBadgeBackgroundColor({ color: '#6366f1' })
    }
  }
)

// src/popup/App.tsx — sending messages
const getPageData = async () => {
  const response = await chrome.runtime.sendMessage<AppMessage, AppMessage>({
    type: 'GET_PAGE_DATA',
  })
  if (response.type === 'PAGE_DATA') setData(response.payload)
}

STORAGE API WRAPPER

// src/shared/storage.ts
export interface ExtConfig {
  theme:       'light' | 'dark'
  apiKey:      string
  autoCapture: boolean
}

const DEFAULTS: ExtConfig = {
  theme: 'light', apiKey: '', autoCapture: false,
}

export const storage = {
  async get(): Promise<ExtConfig> {
    const raw = await chrome.storage.sync.get(DEFAULTS)
    return raw as ExtConfig
  },
  async set(patch: Partial<ExtConfig>): Promise<void> {
    await chrome.storage.sync.set(patch)
  },
  onChange(cb: (changes: Partial<ExtConfig>) => void): void {
    chrome.storage.sync.onChanged.addListener((changes) => {
      const patch: Partial<ExtConfig> = {}
      for (const [key, { newValue }] of Object.entries(changes)) {
        (patch as Record<string, unknown>)[key] = newValue
      }
      cb(patch)
    })
  },
}

CONTENT SCRIPT ISOLATION

// src/content/index.ts — runs in ISOLATED world; can read DOM
import type { AppMessage } from '../shared/messages'

// Observe DOM changes and notify background
const observer = new MutationObserver(() => {
  const count = document.querySelectorAll('[data-item]').length
  chrome.runtime.sendMessage<AppMessage>({ type: 'SET_BADGE', count })
})
observer.observe(document.body, { childList: true, subtree: true })

// src/content/injected.ts — access page JS from MAIN world
// Injected via chrome.scripting.executeScript with world: "MAIN"
// NOTE: Cannot use chrome.* APIs here
window.addEventListener('message', (event) => {
  if (event.source !== window || event.data?.source !== 'my-ext') return
  // Bridge page data → isolated context via postMessage
  window.postMessage({ source: 'my-ext-page', data: window.__appState }, '*')
})

ROUTING TABLE (Message Type → Handler)

Message TypeFromToAction
GET_PAGE_DATAPopupService WorkerExecute script in active tab
PAGE_DATAService WorkerPopupReturn title + URL
SET_BADGEContent ScriptService WorkerUpdate badge count
OPEN_OPTIONSPopupService Workerchrome.runtime.openOptionsPage()
storage.getAnychrome.storage.syncRead config
storage.setOptions pagechrome.storage.syncWrite config
content→bgContentService WorkerDOM event notification
tab.onUpdated—Service WorkerReact on navigation

QUALITY GATES

  • tsc --noEmit — zero errors
  • No eval, new Function(), or innerHTML = userInput
  • Permissions declared in manifest.json — nothing requested at runtime that isn't declared
  • vitest run passes all unit tests
  • npm run build produces clean dist/ (no TS source, no sourcemaps in prod)
  • Extension loads in Chrome without errors in chrome://extensions/
  • Service worker message handlers all return true if async
  • Content script does not access chrome.storage directly in MAIN world scripts

FORBIDDEN

  • ❌ eval() or document.write() — blocked by MV3 CSP
  • ❌ Remote scripts loaded at runtime — all code must be bundled
  • ❌ chrome.tabs.executeScript (MV2 API) — use chrome.scripting.executeScript
  • ❌ Storing tokens in localStorage — use chrome.storage.local
  • ❌ background.js as classic script with DOM access — SW has no DOM
  • ❌ <all_urls> host permission without clear justification
  • ❌ Hardcoded API keys in extension source — fetch from storage
  • ❌ Long-running tasks in service worker without keepalive strategy
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall