Expert — Getting Started

This manual assumes you have edited an MV3 manifest before, that TypeScript and React are everyday tools, and that you have handed code to Claude Code or Codex at some point. Hearing the term FSD before is enough; the six-layer dependency direction and message routing are picked up in the next section, architecture.

What follows is not a command reference. It is the reasoning behind the shape. Walk through that once, and architecture, build-and-package, and distribution all read in context.

The problem in one line

Hand an extension to an AI and the first two or three prompts produce something reasonable. After that, the structure starts drifting. The same feature shows up in two or three places, and the reasoning behind early decisions slips out of memory between sessions. chrome-ext-base puts guardrails exactly where that happens.

Three guardrails

FSD with eslint-plugin-boundaries

Folder layout follows Feature-Sliced Design, and eslint-plugin-boundaries enforces import direction at build time. If the AI tries to cut across layers in arbitrary ways, the build refuses. That alone keeps the model in line for a long stretch.

A single file for message types

Every message type lives in shared/lib/messaging/messages.ts. Every payload that travels between content scripts, the background worker, and popup goes through the discriminated union defined there. The urge to put a new message type in a fresh file is shut down up front.

Backend adapter

shared/api/backend/ holds an adapter strategy. The console-log mode prints payloads to the console and stops there. supabase-direct ships straight to Supabase. server-relay routes through a server you run. Mode selection happens on the options page; the calling code does not know which mode is active. The point of this adapter is letting UI work start before the backend is decided.

ADR habit

Decisions that are expensive to undo go into docs/adr/, one per page. Why permissions were narrowed, why sidePanel was chosen over popup, why the adapter interface looks the way it does. Code records what was done; ADRs record why. The next session, or the next collaborator, picks up the intent without reverse-engineering it from the result.

The ADR template and when to write one sit in docs/adr/README.md.

Automation entry points point at the same place

The Claude Code entry points are .claude/agents/ and .claude/skills/. The Codex entry point is the root AGENTS.md. Both routes read the same single file in the end.

AI_AUTOMATION.md. Domain rules, FSD slice mapping, MV3 forbidden patterns, the six-dimension review checklist, and the phase flow all live there. Two automation tools share one canonical document, so a decision settled in Claude Code carries through a Codex session as well.

What is missing right now

Parts of this base are not finished, and the manual does not hide it. The manual and landing site are public, but the template itself is on a commercial license model. The payment flow and buyer webhook are not wired yet. COMMERCIAL-LICENSE.md is in draft, lawyer review pending. Both have to land before actual sales.

There are gaps on the engineering side too. A smoother zero-config first run, a migration skill for permission changes, an update.xml template for auto-update. The distribution section names these gaps directly instead of papering over them.

What this manual does not cover

OS-specific setup, choosing a Node version manager, walking through a terminal for the first time — none of that lives here. For that, use the Beginner manual. Same base, different pace.

Next

Architecture comes next. How the FSD six layers tie together by dependency direction, how messages route between content scripts, the background worker, and popup, and how the adapter strategy looks from the calling site, with diagrams.