Browser Extension Builder

1---
2name: browser-extension-builder
3description: "Expert in building browser extensions that solve real problems - Chrome, Firefox, and cross-browser extensions. Covers extension architecture, manifest v3, content scripts, popup UIs, monetization strategies, and Chrome Web Store publishing. Use when: browser extension, chrome extension, firefox addon, extension, manifest v3."
4source: vibeship-spawner-skills (Apache 2.0)
5---
6 
7# Browser Extension Builder
8 
9**Role**: Browser Extension Architect
10 
11You extend the browser to give users superpowers. You understand the
12unique constraints of extension development - permissions, security,
13store policies. You build extensions that people install and actually
14use daily. You know the difference between a toy and a tool.
15 
16## Capabilities
17 
18- Extension architecture
19- Manifest v3 (MV3)
20- Content scripts
21- Background workers
22- Popup interfaces
23- Extension monetization
24- Chrome Web Store publishing
25- Cross-browser support
26 
27## Patterns
28 
29### Extension Architecture
30 
31Structure for modern browser extensions
32 
33**When to use**: When starting a new extension
34 
35```javascript
36## Extension Architecture
37 
38### Project Structure
39```
40extension/
41├── manifest.json      # Extension config
42├── popup/
43│   ├── popup.html     # Popup UI
44│   ├── popup.css
45│   └── popup.js
46├── content/
47│   └── content.js     # Runs on web pages
48├── background/
49│   └── service-worker.js  # Background logic
50├── options/
51│   ├── options.html   # Settings page
52│   └── options.js
53└── icons/
54    ├── icon16.png
55    ├── icon48.png
56    └── icon128.png
57```
58 
59### Manifest V3 Template
60```json
61{
62  "manifest_version": 3,
63  "name": "My Extension",
64  "version": "1.0.0",
65  "description": "What it does",
66  "permissions": ["storage", "activeTab"],
67  "action": {
68    "default_popup": "popup/popup.html",
69    "default_icon": {
70      "16": "icons/icon16.png",
71      "48": "icons/icon48.png",
72      "128": "icons/icon128.png"
73    }
74  },
75  "content_scripts": [{
76    "matches": ["<all_urls>"],
77    "js": ["content/content.js"]
78  }],
79  "background": {
80    "service_worker": "background/service-worker.js"
81  },
82  "options_page": "options/options.html"
83}
84```
85 
86### Communication Pattern
87```
88Popup ←→ Background (Service Worker) ←→ Content Script
89              ↓
90        chrome.storage
91```
92```
93 
94### Content Scripts
95 
96Code that runs on web pages
97 
98**When to use**: When modifying or reading page content
99 
100```javascript
101## Content Scripts
102 
103### Basic Content Script
104```javascript
105// content.js - Runs on every matched page
106 
107// Wait for page to load
108document.addEventListener('DOMContentLoaded', () => {
109  // Modify the page
110  const element = document.querySelector('.target');
111  if (element) {
112    element.style.backgroundColor = 'yellow';
113  }
114});
115 
116// Listen for messages from popup/background
117chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
118  if (message.action === 'getData') {
119    const data = document.querySelector('.data')?.textContent;
120    sendResponse({ data });
121  }
122  return true; // Keep channel open for async
123});
124```
125 
126### Injecting UI
127```javascript
128// Create floating UI on page
129function injectUI() {
130  const container = document.createElement('div');
131  container.id = 'my-extension-ui';
132  container.innerHTML = `
133    <div style="position: fixed; bottom: 20px; right: 20px;
134                background: white; padding: 16px; border-radius: 8px;
135                box-shadow: 0 4px 12px rgba(0,0,0,0.15); z-index: 10000;">
136      <h3>My Extension</h3>
137      <button id="my-extension-btn">Click me</button>
138    </div>
139  `;
140  document.body.appendChild(container);
141 
142  document.getElementById('my-extension-btn').addEventListener('click', () => {
143    // Handle click
144  });
145}
146 
147injectUI();
148```
149 
150### Permissions for Content Scripts
151```json
152{
153  "content_scripts": [{
154    "matches": ["https://specific-site.com/*"],
155    "js": ["content.js"],
156    "run_at": "document_end"
157  }]
158}
159```
160```
161 
162### Storage and State
163 
164Persisting extension data
165 
166**When to use**: When saving user settings or data
167 
168```javascript
169## Storage and State
170 
171### Chrome Storage API
172```javascript
173// Save data
174chrome.storage.local.set({ key: 'value' }, () => {
175  console.log('Saved');
176});
177 
178// Get data
179chrome.storage.local.get(['key'], (result) => {
180  console.log(result.key);
181});
182 
183// Sync storage (syncs across devices)
184chrome.storage.sync.set({ setting: true });
185 
186// Watch for changes
187chrome.storage.onChanged.addListener((changes, area) => {
188  if (changes.key) {
189    console.log('key changed:', changes.key.newValue);
190  }
191});
192```
193 
194### Storage Limits
195| Type | Limit |
196|------|-------|
197| local | 5MB |
198| sync | 100KB total, 8KB per item |
199 
200### Async/Await Pattern
201```javascript
202// Modern async wrapper
203async function getStorage(keys) {
204  return new Promise((resolve) => {
205    chrome.storage.local.get(keys, resolve);
206  });
207}
208 
209async function setStorage(data) {
210  return new Promise((resolve) => {
211    chrome.storage.local.set(data, resolve);
212  });
213}
214 
215// Usage
216const { settings } = await getStorage(['settings']);
217await setStorage({ settings: { ...settings, theme: 'dark' } });
218```
219```
220 
221## Anti-Patterns
222 
223### ❌ Requesting All Permissions
224 
225**Why bad**: Users won't install.
226Store may reject.
227Security risk.
228Bad reviews.
229 
230**Instead**: Request minimum needed.
231Use optional permissions.
232Explain why in description.
233Request at time of use.
234 
235### ❌ Heavy Background Processing
236 
237**Why bad**: MV3 terminates idle workers.
238Battery drain.
239Browser slows down.
240Users uninstall.
241 
242**Instead**: Keep background minimal.
243Use alarms for periodic tasks.
244Offload to content scripts.
245Cache aggressively.
246 
247### ❌ Breaking on Updates
248 
249**Why bad**: Selectors change.
250APIs change.
251Angry users.
252Bad reviews.
253 
254**Instead**: Use stable selectors.
255Add error handling.
256Monitor for breakage.
257Update quickly when broken.
258 
259## Related Skills
260 
261Works well with: `frontend`, `micro-saas-launcher`, `personal-tool-builder`
262