브라우저 익스텐션 개발 2026 — Manifest V3 / Plasmo / WXT / Side Panel API / 사파리 익스텐션 심층 가이드

                    Browser Extension API
                            |
        +-------------------+-------------------+
        |                   |                   |
   Chrome (Blink)      Firefox (Gecko)     Safari (WebKit)
        |                   |                   |
   manifest_version: 3   manifest_version: 3   manifest_version: 3
   service_worker        background.scripts    background.scripts
                         (event page)          (persistent: false)
        |                   |                   |
   declarativeNetRequest   webRequest blocking  declarativeNetRequest
                           (MV2 호환 유지)       (제한적 webRequest)
        |                   |                   |
   chrome.* namespace     browser.* + chrome.*  browser.* (Promise)
   Side Panel API         sidebarAction         일부 미지원
   Offscreen Documents    backgroundScripts     일부 미지원

┌──────────────────────────────────────────────────────┐
│                  익스텐션 패키지 (.crx / .xpi / .pkg)  │
├──────────────────────────────────────────────────────┤
│  manifest.json  (메타데이터 + 권한)                    │
│                                                       │
│  ┌─────────────────┐    ┌─────────────────┐         │
│  │ Service Worker  │    │  Content Script │         │
│  │ (background)    │◀──▶│  (페이지 주입)   │         │
│  └─────────────────┘    └─────────────────┘         │
│         ▲                       ▲                    │
│         │                       │                    │
│         ▼                       ▼                    │
│  ┌─────────────────┐    ┌─────────────────┐         │
│  │   Popup / UI    │    │   Side Panel    │         │
│  │  (browser_action)│    │  (Chrome 114+)  │         │
│  └─────────────────┘    └─────────────────┘         │
│                                                       │
│  Offscreen Documents (DOM 필요한 작업)                │
└──────────────────────────────────────────────────────┘

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "description": "A simple MV3 extension",
  "icons": {
    "16": "icons/16.png",
    "48": "icons/48.png",
    "128": "icons/128.png"
  },
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icons/16.png"
  },
  "background": {
    "service_worker": "background.js",
    "type": "module"
  },
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "js": ["content.js"]
    }
  ],
  "permissions": ["storage", "tabs", "sidePanel"],
  "host_permissions": ["https://api.example.com/*"],
  "side_panel": {
    "default_path": "sidepanel.html"
  }
}

[CRX3 Magic: "Cr24"] [Version: 3] [Header Length] [Header (ProtoBuf)]
└─ RSA Signature (개발자 키)
└─ ECDSA Signature (Google 또는 자가)
[ZIP archive of extension files]

[이벤트 발생] -> [Worker 깨움] -> [핸들러 실행] -> [Idle 감지]
                                                       |
                                                       v
                                              [30초 후 종료]

// background.ts
chrome.runtime.onInstalled.addListener(() => {
  console.log('Extension installed')
  chrome.storage.local.set({ installedAt: Date.now() })
})

chrome.action.onClicked.addListener(async (tab) => {
  if (!tab.id) return
  await chrome.scripting.executeScript({
    target: { tabId: tab.id },
    func: () => alert('Hello from extension!'),
  })
})

chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'PING') {
    sendResponse({ type: 'PONG', timestamp: Date.now() })
  }
  return true // 비동기 응답을 위해
})

// 주기 작업은 alarms로
chrome.alarms.create('hourly-sync', { periodInMinutes: 60 })
chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'hourly-sync') {
    syncData()
  }
})

async function syncData() {
  const res = await fetch('https://api.example.com/sync')
  const data = await res.json()
  await chrome.storage.local.set({ lastSync: data })
}

{
  "manifest_version": 3,
  "name": "Simple Ad Blocker",
  "version": "1.0.0",
  "permissions": ["declarativeNetRequest"],
  "host_permissions": ["<all_urls>"],
  "declarative_net_request": {
    "rule_resources": [
      {
        "id": "ruleset_1",
        "enabled": true,
        "path": "rules.json"
      }
    ]
  }
}

[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {
      "urlFilter": "||doubleclick.net^",
      "resourceTypes": ["script", "image", "sub_frame"]
    }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com/blocked" } },
    "condition": {
      "urlFilter": "||tracker.com^",
      "resourceTypes": ["main_frame"]
    }
  }
]

{
  "manifest_version": 3,
  "name": "Side Panel Demo",
  "version": "1.0.0",
  "permissions": ["sidePanel"],
  "side_panel": {
    "default_path": "sidepanel.html"
  },
  "action": {
    "default_title": "Open Side Panel"
  }
}

// background.ts
chrome.runtime.onInstalled.addListener(() => {
  chrome.sidePanel
    .setPanelBehavior({ openPanelOnActionClick: true })
    .catch((error) => console.error(error))
})

// 특정 탭에만 사이드 패널 활성화
chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return
  const url = new URL(tab.url)
  if (url.origin === 'https://www.example.com') {
    await chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel-example.html',
      enabled: true,
    })
  } else {
    await chrome.sidePanel.setOptions({
      tabId,
      enabled: false,
    })
  }
})

{
  "permissions": ["offscreen"]
}

// background.ts
async function ensureOffscreenDocument() {
  const existing = await chrome.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [chrome.runtime.getURL('offscreen.html')],
  })
  if (existing.length > 0) return

  await chrome.offscreen.createDocument({
    url: 'offscreen.html',
    reasons: ['DOM_PARSER'],
    justification: 'Parse HTML for content extraction',
  })
}

chrome.action.onClicked.addListener(async () => {
  await ensureOffscreenDocument()
  const response = await chrome.runtime.sendMessage({
    target: 'offscreen',
    type: 'PARSE_HTML',
    data: '<html>...</html>',
  })
  console.log('parsed:', response)
})

<!-- offscreen.html -->
<!doctype html>
<html>
  <body>
    <script src="offscreen.js"></script>
  </body>
</html>

// offscreen.ts
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.target !== 'offscreen') return
  if (message.type === 'PARSE_HTML') {
    const parser = new DOMParser()
    const doc = parser.parseFromString(message.data, 'text/html')
    const title = doc.querySelector('title')?.textContent ?? ''
    sendResponse({ title })
  }
})

// 함수 주입
await chrome.scripting.executeScript({
  target: { tabId: 123 },
  func: (color) => {
    document.body.style.backgroundColor = color
  },
  args: ['lightblue'],
})

// 파일 주입
await chrome.scripting.executeScript({
  target: { tabId: 123, allFrames: true },
  files: ['content.js'],
})

// CSS 삽입
await chrome.scripting.insertCSS({
  target: { tabId: 123 },
  css: 'body { filter: invert(1); }',
})

// 콘텐츠 스크립트 동적 등록
await chrome.scripting.registerContentScripts([
  {
    id: 'dynamic-script',
    matches: ['https://*.example.com/*'],
    js: ['dynamic.js'],
    runAt: 'document_idle',
  },
])

pnpm create plasmo my-extension
cd my-extension
pnpm dev

my-extension/
├── popup.tsx          # 자동으로 popup이 됨
├── options.tsx        # 자동으로 options page
├── background.ts      # 자동으로 service worker
├── contents/
│   └── plasmo.ts      # content script
├── sidepanel.tsx      # side panel
└── package.json       # manifest의 일부가 됨

{
  "name": "my-extension",
  "displayName": "My Extension",
  "version": "1.0.0",
  "description": "...",
  "manifest": {
    "permissions": ["storage", "tabs"],
    "host_permissions": ["https://*.example.com/*"]
  }
}

// contents/inline.tsx
import type { PlasmoCSConfig } from 'plasmo'
import { useState } from 'react'

export const config: PlasmoCSConfig = {
  matches: ['https://*.example.com/*'],
}

export default function ContentUI() {
  const [count, setCount] = useState(0)
  return (
    <div style={{ position: 'fixed', top: 10, right: 10, background: 'white', padding: 12 }}>
      <button onClick={() => setCount((c) => c + 1)}>Count: {count}</button>
    </div>
  )
}

pnpm dlx wxt@latest init my-extension
cd my-extension
pnpm dev

my-extension/
├── entrypoints/
│   ├── background.ts
│   ├── content.ts
│   ├── popup/
│   │   └── index.html
│   └── options/
├── wxt.config.ts
└── package.json

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

export default defineConfig({
  manifest: {
    permissions: ['storage', 'tabs'],
    host_permissions: ['https://*.example.com/*'],
  },
  modules: ['@wxt-dev/module-react'],
})

// entrypoints/background.ts
export default defineBackground(() => {
  console.log('Hello from background!')
  browser.runtime.onMessage.addListener((msg) => {
    return Promise.resolve({ pong: true })
  })
})

pnpm add -D vite vite-plugin-web-extension

// vite.config.ts
import { defineConfig } from 'vite'
import webExtension from 'vite-plugin-web-extension'
import path from 'path'

export default defineConfig({
  plugins: [
    webExtension({
      manifest: path.resolve('manifest.json'),
      additionalInputs: {
        html: ['sidepanel.html'],
      },
    }),
  ],
})

// 공통 헬퍼
const api = (typeof browser !== 'undefined' ? browser : chrome) as typeof browser

async function getCookie(url: string, name: string) {
  return api.cookies.get({ url, name })
}

import browser from 'webextension-polyfill'

await browser.storage.local.set({ key: 'value' })

{
  "manifest_version": 3,
  "name": "Cross-Browser Ext",
  "version": "1.0.0",
  "background": {
    "scripts": ["background.js"],
    "type": "module"
  },
  "browser_specific_settings": {
    "gecko": {
      "id": "myext@example.com",
      "strict_min_version": "115.0"
    }
  }
}

xcrun safari-web-extension-converter /path/to/extension

[Web Page]
   |  (사용자 액션: 텍스트 선택, 페이지 요약 요청)
   v
[Content Script] -- 페이지 컨텍스트 추출 -->
   |
   v
[Service Worker] -- LLM API 호출 (Claude / OpenAI / 자체) -->
   |
   v
[Side Panel] -- 결과 스트리밍 표시 -->
   |
   v
[사용자]

// sidepanel/App.tsx (WXT + React)
import { useState } from 'react'

export default function SidePanelApp() {
  const [messages, setMessages] = useState<{ role: 'user' | 'assistant'; content: string }[]>([])
  const [input, setInput] = useState('')

  async function send() {
    const userMsg = { role: 'user' as const, content: input }
    setMessages((m) => [...m, userMsg])
    setInput('')

    const response = await chrome.runtime.sendMessage({
      type: 'ASK_LLM',
      messages: [...messages, userMsg],
    })

    setMessages((m) => [...m, { role: 'assistant', content: response.text }])
  }

  return (
    <div className="flex flex-col h-screen p-4">
      <div className="flex-1 overflow-auto">
        {messages.map((m, i) => (
          <div key={i} className={m.role === 'user' ? 'text-blue-600' : 'text-gray-800'}>
            {m.content}
          </div>
        ))}
      </div>
      <div className="flex gap-2">
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          onKeyDown={(e) => e.key === 'Enter' && send()}
          className="flex-1 border p-2"
        />
        <button onClick={send} className="bg-blue-500 text-white px-4">
          Send
        </button>
      </div>
    </div>
  )
}

// background.ts
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'ASK_LLM') {
    callLLM(msg.messages).then((text) => sendResponse({ text }))
    return true // async
  }
})

async function callLLM(messages: any[]) {
  const apiKey = (await chrome.storage.local.get('apiKey')).apiKey
  const res = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'anthropic-version': '2023-06-01',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      model: 'claude-opus-4-7',
      max_tokens: 1024,
      messages,
    }),
  })
  const data = await res.json()
  return data.content[0].text
}

// content.ts
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.type === 'GET_PAGE_TEXT') {
    sendResponse({
      title: document.title,
      url: location.href,
      text: document.body.innerText.slice(0, 50000),
    })
  }
})

// sidepanel: 현재 탭의 텍스트 가져와서 요약 요청
async function summarizeCurrentPage() {
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true })
  if (!tab.id) return
  const pageData = await chrome.tabs.sendMessage(tab.id, { type: 'GET_PAGE_TEXT' })
  // ... LLM 호출
}

// 가용성 확인
const availability = await ai.languageModel.availability()
if (availability === 'available') {
  const session = await ai.languageModel.create()
  const response = await session.prompt('Summarize: ...')
}

// chrome.identity.launchWebAuthFlow를 통한 OAuth
async function loginWithKakao() {
  const clientId = 'YOUR_KAKAO_REST_API_KEY'
  const redirectUri = chrome.identity.getRedirectURL()
  const authUrl =
    `https://kauth.kakao.com/oauth/authorize?` +
    `client_id=${clientId}&` +
    `redirect_uri=${encodeURIComponent(redirectUri)}&` +
    `response_type=code`

  const responseUrl = await chrome.identity.launchWebAuthFlow({
    url: authUrl,
    interactive: true,
  })

  const code = new URL(responseUrl!).searchParams.get('code')
  // code를 백엔드로 보내서 토큰 교환
  return code
}

{
  "permissions": ["activeTab"],
  "optional_host_permissions": ["https://*.example.com/*"]
}

{
  "content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'self'"
  }
}

{
  "externally_connectable": {
    "matches": ["https://yoursite.com/*"]
  }
}

// Vitest로 헬퍼 함수 테스트
import { describe, it, expect, vi } from 'vitest'
import { syncData } from './background'

global.chrome = {
  storage: {
    local: {
      set: vi.fn(),
      get: vi.fn().mockResolvedValue({}),
    },
  },
  alarms: {
    create: vi.fn(),
    onAlarm: { addListener: vi.fn() },
  },
} as any

describe('syncData', () => {
  it('saves data to storage', async () => {
    await syncData()
    expect(chrome.storage.local.set).toHaveBeenCalled()
  })
})

import { test, expect, chromium } from '@playwright/test'
import path from 'path'

test('extension loads', async () => {
  const pathToExtension = path.resolve(__dirname, '../.output/chrome-mv3')
  const context = await chromium.launchPersistentContext('', {
    headless: false,
    args: [
      `--disable-extensions-except=${pathToExtension}`,
      `--load-extension=${pathToExtension}`,
    ],
  })

  const page = await context.newPage()
  await page.goto('https://example.com')

  // content script가 주입되었는지 확인
  const injected = await page.evaluate(() => (window as any).__MY_EXT_LOADED__)
  expect(injected).toBe(true)

  await context.close()
})

# .github/workflows/release.yml
name: Build and Release
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm test
      - run: pnpm build --target chrome-mv3
      - run: pnpm build --target firefox-mv3
      - uses: actions/upload-artifact@v4
        with:
          name: extensions
          path: .output/

  publish-chrome:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
      - name: Upload to Chrome Web Store
        uses: PlasmoHQ/bpp@v3
        with:
          keys: $TEST_KEYS_PLACEHOLDER
          chrome-file: extensions/chrome-mv3.zip