Build a Chrome Extension

The Big Idea

The author built a Bilibili creator-assistant extension "out of pure laziness" — dozens of comments needed replies every day. The first version ran in about two hours, but all the code was crammed into one 1,211-line content.js where "any change felt like defusing a bomb." A later v3.0 refactor shrank content.js to 175 lines across 7 independent modules.

Why Chrome Extensions Are a Good Project

Phase 0 — Requirements Analysis

The early mistake: jumping straight to "build an auto-reply plugin." Claude produced a very basic version (detect a new comment, reply "Thanks for your support") — functional, but not what was wanted.

The fix: enter Plan mode first (Shift+Tab) and talk through requirements:

I want to build a Bilibili creator assistant Chrome extension. Core requirements:
1. Automatically scan video comments
2. Match comments against keyword rules and auto-reply
3. Support both global rules and per-video rules
4. Don't re-reply to comments that have already been replied to
5. A simple management panel to view running status
Help me analyze these requirements first and propose a technical approach.

In Plan mode Claude outputs a full technical proposal — file structure, technology choices, analysis of tricky parts. Do not rush to say "great, let's start." Read it carefully and raise questions.

Phase 1 — Project Initialization

Based on the approach we discussed, create the Chrome extension project. Start with the skeleton:
- manifest.json (MV3)
- background.js (Service Worker)
- content.js (Content Script)
- popup.html + popup.js (management panel)
- lib/ directory (business modules)
Only request permissions that are strictly necessary.

Code example: manifest.json (the "soul" of an extension)

{
  "manifest_version": 3,
  "name": "Bilibili Creator Assistant",
  "version": "3.0.0",
  "permissions": ["storage", "alarms", "activeTab"],
  "host_permissions": ["*://*.bilibili.com/*"],
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [{
    "matches": ["*://*.bilibili.com/video/*"],
    "js": ["content.js"]
  }],
  "action": {
    "default_popup": "popup.html"
  }
}

Explaining the key decisions

Phase 2 — Core Architecture: Who Owns What

The most common mistake in extension development is putting code in the wrong place. MV3 has three runtime environments with completely different responsibilities:

The v3 architecture

background.js (Command Center)
  ├── Owns the timed scan loop (chrome.alarms, once per minute)
  ├── Routes all messages (popup/content/widget -> centralized handling)
  └── Manages global state (on/off switch, rate limit level, etc.)
       ↕  chrome.runtime.sendMessage
content.js (Front-line Scout)
  ├── Extracts current video info (BV ID, title, etc.)
  ├── Proxies API calls (requires page cookies)
  └── Forwards logs and status to the floating widget
       ↕  Message passing
lib/ (Business Brain)
  ├── db.js         -> Unified data layer, all storage reads/writes go here
  ├── scanner.js    -> Comment scanning engine
  ├── rules.js      -> Rule matching logic
  ├── api.js        -> Bilibili API wrapper
  ├── ai.js         -> AI reply generation
  └── rate-limiter.js -> 4-level rate limiting with graceful degradation

The key design principle: content.js only does what it absolutely must — read page cookies (background.js cannot in MV3) and manipulate page DOM. Everything else lives in background.js and lib/.

Architecture principles:
1. content.js is a thin shell - only extracts video info and proxies API calls
2. background.js is the command center - owns the scan loop and state management
3. All business logic goes in independent modules under lib/
4. All data storage goes through lib/db.js - no direct chrome.storage calls elsewhere
5. Modules communicate via message passing, not shared state
Write these into the project's CLAUDE.md.

Phase 3 — Building Modules One by One

Code example: dependency injection in scanner.js

async function scanOneVideo(bvid, rules, config, {
  sendReplyFn,        // function to send a reply
  fetchCommentsFn,    // function to fetch comments
  logFn               // logging function
}) {
  // business logic
}

Explaining the code

scanner.js runs inside background.js, but API calls must execute in the content.js context. Instead of calling the API directly, scanOneVideo receives functions from outside. background.js passes in a function that "relays the call to content.js via messaging," and scanner.js never needs to know that detail. This keeps the business logic testable and decoupled from the messaging plumbing.

The 4-level rate limiter

A successful reply decrements the error counter, automatically recovering to normal — "like a spring: compress it, and it bounces back."

Phase 4 — Debugging Tips

Phase 5 — Installation and Testing

During development you do not publish to the Chrome Web Store. On chrome://extensions, enable "Developer mode," click "Load unpacked," and select your project directory.

A testing checklist (have Claude generate one):

• Basic functionality: add a rule → scan comments → auto-reply
• Deduplication: the same comment is never replied to twice
• Rate limiting: rapid consecutive replies automatically slow down
• Persistence: close the browser and reopen — state and data are preserved
• Multiple tabs: open several video pages at once, each running independently

Real-World Story: From 1,211 Lines to 175

Version 1 worked, but content.js was one 1,211-line file with API calls, scanning logic, rule matching, and UI updates all tangled together. MV3 Service Workers can sleep at any time, making setInterval scheduling unreliable. The refactor was not planned — the author wanted to add AI-assisted replies and found it impossible to work with in that file.

The current content.js is 1,211 lines with all logic mixed together. I want to refactor it into:
- background.js as the operational hub
- content.js as a thin shell (only video info extraction and API proxying)
- lib/ directory for all business modules
Don't do this all at once - work in steps. First help me analyze the current code and map out where each part belongs.

Claude produced a migration plan splitting the 1,211 lines into 8 functional chunks, annotating where each belonged. Then they executed step by step — test after each migration, confirm nothing regressed, then move on.

The final result

Real-World Use Cases: Other Extension Ideas

Whichever you choose, the core workflow is the same: Plan mode to analyze requirements → define architecture (who owns what) → write CLAUDE.md to lock in the principles → implement module by module → debug and test.

Visual Mental Model: The Three MV3 Environments

          ┌─────────────────────────────────────────────┐
          │  POPUP / OPTIONS  (popup.js)                 │
          │  UI + config  ·  dies when popup closes      │
          └───────────────┬─────────────────────────────┘
                          │ messages
   ┌──────────────────────▼──────────────────────┐
   │  SERVICE WORKER  (background.js)             │  <- alarms, global state,
   │  command center  ·  can be killed anytime   │     message routing
   └──────────────────────┬──────────────────────┘
                          │ messages
   ┌──────────────────────▼──────────────────────┐
   │  CONTENT SCRIPT  (content.js)  THIN SHELL    │  <- DOM + page cookies ONLY
   └─────────────────────────────────────────────┘
   lib/*  =  all business logic, called from background.js

Important Comparisons

Common Beginner Mistakes

• Jumping to "build the plugin" without a Plan-mode requirements discussion.
• Putting code in the wrong environment — e.g. business logic in content.js.
• Using setInterval in an MV3 Service Worker instead of chrome.alarms.
• Letting Claude reference MV2 tutorials, mixing the two APIs.
• Requesting more permissions than needed — risks store rejection and scares users.
• Direct chrome.storage calls scattered everywhere instead of one data layer.
• Refactoring everything in one shot instead of step-by-step with tests.
• Chasing fewer lines instead of clearer responsibilities.

Best Practices

• Start in Plan mode and read the proposal before coding.
• Decide "who owns what" across the three MV3 environments before writing modules.
• Encode architecture principles in CLAUDE.md so every session respects them (incl. "Must use Manifest V3", "use chrome.alarms").
• Request minimal permissions.
• Build bottom-up: data layer first, UI last.
• Route all storage through one db.js; make writes atomic (read → merge → write).
• Use dependency injection to keep business logic testable and decoupled from messaging.
• Add a logging system for debugging (e.g. last 200 entries in the popup).
• Refactor in steps, testing after each migration.
• Optimise for reduced cognitive overhead, not line count.

Interview / Revision Questions

1. Why is a Chrome extension a good project after the earlier chapters?
2. What is the instant feedback loop for extension development?
3. What mistake does jumping straight to "build the plugin" cause, and what is the fix?
4. What are the three MV3 runtime environments, and what can each one not do?
5. Why can't you use setInterval in an MV3 Service Worker?
6. What is the "key design principle" for content.js?
7. What are the five architecture principles written into CLAUDE.md?
8. In what order are modules built, and why is db.js first?
9. Explain dependency injection in scanner.js and why it is used.
10. Describe the 4-level rate limiter and how it recovers.
11. Where do background.js logs appear versus content.js logs?
12. What is the real point of the 1,211 → 175 refactor, given total lines went up?

Practice Exercises

Quick Memory Map

Build a Chrome Extension
│
├── Goal: MAINTAINABLE, not just runnable
│
├── Workflow
│   Plan mode (requirements) -> architecture (who owns what)
│   -> CLAUDE.md (lock principles) -> module by module -> debug + test
│
├── MV3 environments
│   ├── Service Worker (background.js): alarms, state, routing; NO DOM/cookies; can be killed
│   ├── Content Script (content.js): DOM + page cookies ONLY (thin shell)
│   └── Popup/Options (popup.js): UI + config; dies on close
│   -> setInterval OUT, chrome.alarms IN
│
├── Build order: db.js -> rules.js -> api.js -> scanner.js
│                 -> rate-limiter.js -> background.js -> content.js + UI
│   ├── all storage via db.js, atomic read->merge->write
│   └── scanner.js uses dependency injection (sendReplyFn, fetchCommentsFn, logFn)
│
├── Rate limiter: normal -> slow -> slower -> paused (recovers on success)
│
├── Debug: SW logs in SW DevTools; CS logs in page DevTools; reload per environment
│
└── Refactor story: 1,211-line content.js -> 175 lines + modules
    (more total lines, LESS cognitive overhead; migrate in tested steps)

Complete Chapter Revision

1. Build a real, maintainable Chrome extension, not a toy.
2. Extensions suit Claude Code: right technical barrier, real daily use, instant feedback loop.
3. Phase 0: discuss requirements in Plan mode before coding — it always beats rebuilding later.
4. Phase 1: scaffold with MV3; manifest.json uses manifest_version 3, a Service Worker, and minimal permissions.
5. Phase 2: MV3 has three environments with distinct jobs; content.js is a thin shell (DOM + cookies only); all logic lives in background.js and lib/; write the principles into CLAUDE.md.
6. Phase 3: build bottom-up — db.js first (5 structured keys, atomic writes), then rules.js, api.js, scanner.js (dependency injection), rate-limiter.js (4 levels), background.js, then UI.
7. Phase 4: debug each environment separately; reload rules differ per environment; add a log system.
8. Phase 5: "Load unpacked" in Developer mode; run a checklist covering functionality, dedup, rate limiting, persistence, multi-tab.
9. The 1,211 → 175 refactor: migrate in tested steps; total lines rose but cognitive overhead fell.
10. Same workflow applies to any extension idea (annotation, translation, timer, GitHub enhancer).

Final Takeaway

This teaching edition is based on the supplied April 2026, 2nd edition of Claude Code: The Complete Guide (§11, "Hands-on Project: Chrome Extension"). Manifest V3 details, Chrome APIs, file/line counts and the sample project reflect that edition and may change over time.