my-extension/
├── manifest.json          # Required: extension configuration
├── icons/
│   ├── icon16.png
│   ├── icon48.png
│   └── icon128.png
├── background.js          # Service worker (event-driven)
├── popup/
│   ├── popup.html
│   ├── popup.js
│   └── popup.css
├── content/
│   ├── content.js         # Injected into web pages
│   └── content.css
├── options/
│   ├── options.html
│   ├── options.js
│   └── options.css
├── sidepanel/
│   ├── sidepanel.html
│   └── sidepanel.js
└── _locales/              # Optional: internationalization
    └── en/
        └── messages.json

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "description": "A brief description of the extension.",
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  }
}

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "description": "What it does in one sentence.",
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "action": {
    "default_popup": "popup/popup.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png"
    },
    "default_title": "Click me"
  },
  "background": {
    "service_worker": "background.js",
    "type": "module"
  },
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "js": ["content/content.js"],
      "css": ["content/content.css"],
      "run_at": "document_idle"
    }
  ],
  "permissions": [
    "storage",
    "activeTab",
    "contextMenus",
    "alarms",
    "notifications"
  ],
  "optional_permissions": [
    "tabs",
    "history",
    "bookmarks"
  ],
  "host_permissions": [
    "https://api.example.com/*"
  ],
  "optional_host_permissions": [
    "https://*/*"
  ],
  "options_page": "options/options.html",
  "side_panel": {
    "default_path": "sidepanel/sidepanel.html"
  },
  "web_accessible_resources": [
    {
      "resources": ["images/*", "styles/*"],
      "matches": ["https://*.example.com/*"]
    }
  ],
  "content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'self'"
  },
  "externally_connectable": {
    "matches": ["https://*.example.com/*"]
  },
  "commands": {
    "_execute_action": {
      "suggested_key": { "default": "Ctrl+Shift+Y" },
      "description": "Open the popup"
    },
    "toggle-feature": {
      "suggested_key": { "default": "Ctrl+Shift+U" },
      "description": "Toggle the feature"
    }
  },
  "minimum_chrome_version": "116"
}

// Request optional permission when user clicks a button
document.getElementById('enable-feature').addEventListener('click', async () => {
  const granted = await chrome.permissions.request({
    permissions: ['history'],
    origins: ['https://api.example.com/*']
  });
  if (granted) {
    enableHistoryFeature();
  }
});

// background.js

// Runs once on install or update
chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === 'install') {
    // First install: set defaults
    chrome.storage.local.set({
      settings: { enabled: true, theme: 'light' },
      stats: { totalUses: 0 }
    });

    // Create context menu
    chrome.contextMenus.create({
      id: 'myContextMenu',
      title: 'Do something with "%s"',
      contexts: ['selection']
    });
  }

  if (details.reason === 'update') {
    console.log(`Updated from ${details.previousVersion}`);
  }
});

// Handle context menu clicks
chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'myContextMenu') {
    const selectedText = info.selectionText;
    // Process the selected text
    chrome.tabs.sendMessage(tab.id, {
      action: 'processSelection',
      text: selectedText
    });
  }
});

// Handle messages from content scripts or popup
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === 'getData') {
    fetchData(message.query).then(sendResponse);
    return true; // Keep channel open for async response
  }

  if (message.action === 'getTabInfo') {
    sendResponse({ tabId: sender.tab?.id, url: sender.tab?.url });
  }
});

// Alarms for periodic tasks
chrome.alarms.create('periodicSync', { periodInMinutes: 30 });

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

async function fetchData(query) {
  const response = await fetch(`https://api.example.com/search?q=${query}`);
  return response.json();
}

async function syncData() {
  const { settings } = await chrome.storage.local.get('settings');
  if (settings.enabled) {
    // Perform sync
  }
}

// WRONG: listener registered inside async callback (may be lost)
chrome.storage.local.get('config').then(({ config }) => {
  chrome.runtime.onMessage.addListener(handler); // May not register!
});

// CORRECT: register listener at top level
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // Access storage inside the handler
  chrome.storage.local.get('config').then(({ config }) => {
    // Use config
    sendResponse({ result: config });
  });
  return true;
});

"content_scripts": [
  {
    "matches": ["https://*.example.com/*", "https://other-site.com/page/*"],
    "exclude_matches": ["https://example.com/admin/*"],
    "js": ["content/content.js"],
    "css": ["content/content.css"],
    "run_at": "document_idle",
    "all_frames": false
  }
]

// From background.js or popup.js — requires "scripting" permission
chrome.scripting.executeScript({
  target: { tabId: tabId },
  files: ['content/inject.js']
});

// Inject a function directly
chrome.scripting.executeScript({
  target: { tabId: tabId },
  func: (param) => {
    document.title = `Modified: ${param}`;
    return document.title;
  },
  args: ['hello']
});

// Inject CSS
chrome.scripting.insertCSS({
  target: { tabId: tabId },
  css: 'body { border: 2px solid red; }'
});

// Register at runtime — persists across restarts
chrome.scripting.registerContentScripts([
  {
    id: 'my-script',
    matches: ['https://*.example.com/*'],
    js: ['content/dynamic.js'],
    runAt: 'document_idle'
  }
]);

// Unregister
chrome.scripting.unregisterContentScripts({ ids: ['my-script'] });

// content/content.js

// Wait for DOM ready
function init() {
  // Add custom UI
  const panel = document.createElement('div');
  panel.id = 'my-extension-panel';
  panel.innerHTML = `
    <div style="position:fixed;bottom:10px;right:10px;z-index:99999;
                background:#fff;border:1px solid #ccc;padding:12px;
                border-radius:8px;box-shadow:0 2px 8px rgba(0,0,0,0.15);
                font-family:system-ui;">
      <h3 style="margin:0 0 8px">My Extension</h3>
      <button id="my-ext-btn">Click Me</button>
      <div id="my-ext-output"></div>
    </div>
  `;
  document.body.appendChild(panel);

  document.getElementById('my-ext-btn').addEventListener('click', async () => {
    // Send message to background
    const response = await chrome.runtime.sendMessage({
      action: 'getData',
      query: document.title
    });
    document.getElementById('my-ext-output').textContent = JSON.stringify(response);
  });
}

if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', init);
} else {
  init();
}

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    body {
      width: 320px;
      min-height: 200px;
      padding: 16px;
      font-family: system-ui, -apple-system, sans-serif;
      margin: 0;
    }
    h1 { font-size: 18px; margin: 0 0 12px; }
    button {
      padding: 8px 16px;
      border: none;
      border-radius: 6px;
      background: #4285f4;
      color: white;
      cursor: pointer;
      font-size: 14px;
    }
    button:hover { background: #3367d6; }
    #output {
      margin-top: 12px;
      padding: 8px;
      background: #f5f5f5;
      border-radius: 4px;
      font-size: 13px;
      word-break: break-all;
    }
  </style>
</head>
<body>
  <h1>My Extension</h1>
  <button id="action-btn">Do Something</button>
  <div id="output"></div>
  <script src="popup.js"></script>
</body>
</html>

document.getElementById('action-btn').addEventListener('click', async () => {
  const output = document.getElementById('output');

  // Get current tab
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });

  // Send message to content script
  try {
    const response = await chrome.tabs.sendMessage(tab.id, {
      action: 'getPageData'
    });
    output.textContent = JSON.stringify(response, null, 2);
  } catch (err) {
    output.textContent = `Error: ${err.message}`;
  }
});

// Load saved state on popup open
document.addEventListener('DOMContentLoaded', async () => {
  const { settings } = await chrome.storage.local.get('settings');
  if (settings) {
    // Apply saved settings to UI
  }
});

{
  "permissions": ["sidePanel"],
  "side_panel": {
    "default_path": "sidepanel/sidepanel.html"
  }
}

// background.js — open side panel instead of popup
chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });

// background.js — enable side panel only on certain sites
chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  await chrome.sidePanel.setOptions({
    tabId,
    path: 'sidepanel/sidepanel.html',
    enabled: url.hostname === 'github.com'
  });
});

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    body { font-family: system-ui; padding: 20px; max-width: 500px; }
    label { display: block; margin: 12px 0 4px; font-weight: 600; }
    input[type="text"], select {
      width: 100%; padding: 8px; border: 1px solid #ccc;
      border-radius: 4px; box-sizing: border-box;
    }
    .saved { color: green; display: none; margin-top: 8px; }
    button { margin-top: 16px; padding: 8px 24px; }
  </style>
</head>
<body>
  <h1>Extension Settings</h1>
  <label for="apiKey">API Key</label>
  <input type="text" id="apiKey" placeholder="Enter your API key">

  <label for="theme">Theme</label>
  <select id="theme">
    <option value="light">Light</option>
    <option value="dark">Dark</option>
    <option value="auto">Auto</option>
  </select>

  <label>
    <input type="checkbox" id="notifications"> Enable notifications
  </label>

  <button id="save">Save Settings</button>
  <div class="saved" id="saved-msg">Settings saved!</div>

  <script src="options.js"></script>
</body>
</html>

// Load saved settings
document.addEventListener('DOMContentLoaded', async () => {
  const { settings } = await chrome.storage.sync.get('settings');
  if (settings) {
    document.getElementById('apiKey').value = settings.apiKey || '';
    document.getElementById('theme').value = settings.theme || 'light';
    document.getElementById('notifications').checked = settings.notifications ?? true;
  }
});

// Save settings
document.getElementById('save').addEventListener('click', async () => {
  const settings = {
    apiKey: document.getElementById('apiKey').value,
    theme: document.getElementById('theme').value,
    notifications: document.getElementById('notifications').checked
  };

  await chrome.storage.sync.set({ settings });

  const msg = document.getElementById('saved-msg');
  msg.style.display = 'block';
  setTimeout(() => msg.style.display = 'none', 2000);
});

// Write
await chrome.storage.local.set({ key: 'value', complex: { nested: true } });

// Read
const { key, complex } = await chrome.storage.local.get(['key', 'complex']);

// Read all
const allData = await chrome.storage.local.get(null);

// Remove
await chrome.storage.local.remove('key');
await chrome.storage.local.remove(['key1', 'key2']);

// Clear everything
await chrome.storage.local.clear();

// Watch for changes (works in all contexts)
chrome.storage.onChanged.addListener((changes, areaName) => {
  for (const [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(`[${areaName}] ${key}: ${oldValue} -> ${newValue}`);
  }
});

// background.js — use storage.session for temporary state
// since service workers can be terminated at any time

async function incrementCounter() {
  const { count = 0 } = await chrome.storage.session.get('count');
  await chrome.storage.session.set({ count: count + 1 });
  return count + 1;
}

// Content script or popup -> Service worker
const response = await chrome.runtime.sendMessage({
  action: 'fetchData',
  url: 'https://api.example.com/data'
});

// Service worker -> Content script (specific tab)
const response = await chrome.tabs.sendMessage(tabId, {
  action: 'highlight',
  selector: '.target'
});

// Service worker listener
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === 'fetchData') {
    fetch(message.url)
      .then(r => r.json())
      .then(sendResponse)
      .catch(err => sendResponse({ error: err.message }));
    return true; // REQUIRED for async sendResponse
  }
});

// Content script
const port = chrome.runtime.connect({ name: 'stream' });
port.postMessage({ subscribe: 'updates' });
port.onMessage.addListener((msg) => {
  console.log('Received:', msg);
});
port.onDisconnect.addListener(() => {
  console.log('Port closed');
});

// Service worker
chrome.runtime.onConnect.addListener((port) => {
  if (port.name !== 'stream') return;
  port.onMessage.addListener((msg) => {
    if (msg.subscribe === 'updates') {
      // Send periodic updates
      port.postMessage({ update: 'new data' });
    }
  });
});

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

// On your website
chrome.runtime.sendMessage('YOUR_EXTENSION_ID', { action: 'login', token: 'abc' },
  (response) => { console.log(response); }
);

// In service worker
chrome.runtime.onMessageExternal.addListener((message, sender, sendResponse) => {
  if (sender.origin !== 'https://yoursite.com') return;
  sendResponse({ success: true });
});

// background.js
chrome.runtime.onInstalled.addListener(() => {
  // Parent menu
  chrome.contextMenus.create({
    id: 'parent',
    title: 'My Extension',
    contexts: ['all']
  });

  // Child items
  chrome.contextMenus.create({
    id: 'search-selection',
    parentId: 'parent',
    title: 'Search "%s"',
    contexts: ['selection']
  });

  chrome.contextMenus.create({
    id: 'save-image',
    parentId: 'parent',
    title: 'Save this image',
    contexts: ['image']
  });

  chrome.contextMenus.create({
    id: 'open-link',
    parentId: 'parent',
    title: 'Open in new tab',
    contexts: ['link']
  });
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  switch (info.menuItemId) {
    case 'search-selection':
      chrome.tabs.create({
        url: `https://google.com/search?q=${encodeURIComponent(info.selectionText)}`
      });
      break;
    case 'save-image':
      chrome.downloads.download({ url: info.srcUrl });
      break;
    case 'open-link':
      chrome.tabs.create({ url: info.linkUrl });
      break;
  }
});

// manifest.json
{
  "permissions": ["declarativeNetRequest"],
  "declarative_net_request": {
    "rule_resources": [
      {
        "id": "my_rules",
        "enabled": true,
        "path": "rules.json"
      }
    ]
  }
}

// rules.json
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {
      "urlFilter": "tracker.example.com",
      "resourceTypes": ["script", "image", "xmlhttprequest"]
    }
  },
  {
    "id": 2,
    "priority": 1,
    "action": {
      "type": "redirect",
      "redirect": { "url": "https://new-api.example.com/v2" }
    },
    "condition": {
      "urlFilter": "old-api.example.com/v1",
      "resourceTypes": ["xmlhttprequest"]
    }
  },
  {
    "id": 3,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "requestHeaders": [
        { "header": "X-Custom", "operation": "set", "value": "my-value" }
      ]
    },
    "condition": {
      "urlFilter": "api.example.com",
      "resourceTypes": ["xmlhttprequest"]
    }
  }
]

// Add rules at runtime
chrome.declarativeNetRequest.updateDynamicRules({
  addRules: [
    {
      id: 100,
      priority: 1,
      action: { type: 'block' },
      condition: { urlFilter: 'ads.example.com', resourceTypes: ['script'] }
    }
  ],
  removeRuleIds: [100] // Remove existing rule with this ID first
});

{
  "devtools_page": "devtools/devtools.html"
}

<!DOCTYPE html>
<html>
<body>
  <script src="devtools.js"></script>
</body>
</html>

chrome.devtools.panels.create(
  'My Panel',
  'icons/icon16.png',
  'devtools/panel.html',
  (panel) => {
    panel.onShown.addListener((window) => {
      // Panel is visible
    });
  }
);

// Access inspected page
chrome.devtools.inspectedWindow.eval(
  'document.querySelectorAll("a").length',
  (result, error) => {
    if (!error) console.log(`Found ${result} links`);
  }
);

// Set badge
chrome.action.setBadgeText({ text: '42' });
chrome.action.setBadgeBackgroundColor({ color: '#4285f4' });

// Change icon dynamically
chrome.action.setIcon({
  path: { "16": "icons/active16.png", "48": "icons/active48.png" }
});

// Disable for specific tab
chrome.action.disable(tabId);
chrome.action.enable(tabId);

// Handle click (when no popup is set)
chrome.action.onClicked.addListener((tab) => {
  // Toggle something on click
  chrome.scripting.executeScript({
    target: { tabId: tab.id },
    files: ['content/toggle.js']
  });
});

// manifest.json
"commands": {
  "_execute_action": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y",
      "mac": "Command+Shift+Y"
    },
    "description": "Open the extension"
  },
  "toggle-feature": {
    "suggested_key": {
      "default": "Alt+T"
    },
    "description": "Toggle the feature"
  }
}

// background.js
chrome.commands.onCommand.addListener((command, tab) => {
  if (command === 'toggle-feature') {
    chrome.tabs.sendMessage(tab.id, { action: 'toggle' });
  }
});

{
  "permissions": ["tabs"],
  "action": { "default_popup": "popup/popup.html" }
}

// popup.js
const tabs = await chrome.tabs.query({ currentWindow: true });
tabs.forEach(tab => {
  // Render tab list
});

// Close duplicate tabs
const seen = new Map();
for (const tab of tabs) {
  if (seen.has(tab.url)) {
    chrome.tabs.remove(tab.id);
  } else {
    seen.set(tab.url, tab.id);
  }
}

// background.js
const enabledTabs = new Set();

chrome.action.onClicked.addListener(async (tab) => {
  if (enabledTabs.has(tab.id)) {
    enabledTabs.delete(tab.id);
    chrome.action.setBadgeText({ text: '', tabId: tab.id });
    chrome.scripting.removeCSS({ target: { tabId: tab.id }, files: ['content/styles.css'] });
  } else {
    enabledTabs.add(tab.id);
    chrome.action.setBadgeText({ text: 'ON', tabId: tab.id });
    chrome.scripting.insertCSS({ target: { tabId: tab.id }, files: ['content/styles.css'] });
    chrome.scripting.executeScript({ target: { tabId: tab.id }, files: ['content/modifier.js'] });
  }
});

// background.js
chrome.runtime.onInstalled.addListener(() => {
  chrome.alarms.create('check-updates', { periodInMinutes: 15 });
});

chrome.alarms.onAlarm.addListener(async (alarm) => {
  if (alarm.name === 'check-updates') {
    const data = await fetch('https://api.example.com/updates').then(r => r.json());
    if (data.hasUpdates) {
      chrome.notifications.create({
        type: 'basic',
        iconUrl: 'icons/icon128.png',
        title: 'New Updates Available',
        message: data.summary
      });
    }
  }
});

# From the extension directory
zip -r extension.zip . -x "*.git*" "node_modules/*" "*.map" "*.ts" "src/*"

// vite.config.js
import { defineConfig } from 'vite';
import { resolve } from 'path';

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        popup: resolve(__dirname, 'popup/popup.html'),
        options: resolve(__dirname, 'options/options.html'),
        background: resolve(__dirname, 'background.js'),
        content: resolve(__dirname, 'content/content.js'),
      },
      output: {
        entryFileNames: '[name].js',
        chunkFileNames: '[name].js',
        assetFileNames: '[name].[ext]'
      }
    },
    outDir: 'dist',
    emptyOutDir: true
  }
});

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noEmit": true,
    "types": ["chrome"]
  },
  "include": ["src/**/*.ts"]
}

npm install -D typescript @types/chrome