react-spa

react-spa — Claude Plugin

A React SPA frontend development plugin for Claude Code. Provides a structured 7-phase workflow with TDD enforcement, codebase memory caching, and feature branch management.

Works with any React + TypeScript project. No project-specific configuration required — the plugin discovers your stack automatically.

---

Install

Step 1 — Add this repo as a marketplace (one-time per machine):

/plugin marketplace add dyeoh/claude-plugin-react-spa-fe-dev

Step 2 — Install the plugin:

/plugin install react-spa@dyeoh-claude-plugin-react-spa-fe-dev

Both commands are typed directly into Claude Code (CLI or VS Code extension) — not in a terminal.

---

Usage

/react-spa Add a positions table with live price updates
/react-spa Refactor the order modal to use a Radix Dialog
/react-spa          ← launches interactively, asks what to build

---

What It Does

7-Phase Workflow

Phase	Goal
1. Cache & Orientation	Read .react-spa-cache.md — understand existing components without re-scanning
2. Feature Scoping	Clarify exactly what's being built before touching any file
3. Codebase Exploration	Launch component-explorer agents to map existing patterns
4. Component Design	Launch component-architect to design component tree + types + test scenarios
5. TDD Implementation	Red-Green-Refactor per component — test first, always
6. Quality Review	Launch component-reviewer agents for TypeScript, a11y, coverage, conventions
7. Commit & Summary	Stage + commit on feature branch, update cache, document session

Codebase Memory Cache

The plugin maintains .react-spa-cache.md in your project. On each invocation it checks the cache's last_commit header against the latest git commit to the source directory. If the commit matches, it skips re-scanning — saving significant token usage on repeat sessions.

Cache is updated automatically at the end of each session with new components, hooks, and API types added.

TDD Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

The plugin enforces Red-Green-Refactor strictly:

• Write one failing test
• Watch it fail (mandatory)
• Write minimal code to pass
• Watch it pass
• Refactor
• Repeat

Rationales for skipping TDD are documented and rejected inline.

Feature Branches

Every feature gets its own branch:

feature/<name>        ← standard feature work
hotfix/<description>  ← bug fixes

---

Specialized Agents

The plugin ships with 3 agents that are invoked automatically within the workflow (they can also be used standalone):

component-explorer

Maps the existing codebase: component structure, data-fetching patterns, state management, test conventions, TypeScript style, and UI library. Returns an inventory of what exists so new code follows established patterns.

Standalone usage:

"Launch component-explorer to map how authentication components are organised"
"Launch component-explorer to understand the data-fetching patterns in this project"

component-architect

Designs a complete component blueprint given a feature request: component tree with file paths, props interfaces, state ownership decisions, required API types, and plain-English test scenarios. Output is ready to hand directly to TDD implementation.

Standalone usage:

"Launch component-architect to design a positions table with polling"
"Launch component-architect to design the order confirmation flow"

component-reviewer

Reviews components for TypeScript correctness, accessibility, test coverage, and project conventions. Returns issues grouped by severity (Critical / Important / Minor) with confidence scores — only reports findings above 70% confidence.

Standalone usage:

"Launch component-reviewer on src/features/trading/components/"
"Launch component-reviewer to check my recent changes for accessibility issues"

---

Cache File Format

The plugin creates and maintains .react-spa-cache.md in your project root (or cache/.react-spa-cache.md if a cache/ directory exists). Format:

<!-- REACT SPA CACHE — AUTO-GENERATED BY react-spa PLUGIN -->
<!-- cache_date: YYYY-MM-DD -->
<!-- last_commit: abc1234 -->
<!-- source_root: src/ -->

## Stack
...

## Component Registry
| Component | File | Status | Tests |
...

## Hook Registry
| Hook | File | Status |
...

## API Types Coverage
...

Add .react-spa-cache.md to .gitignore if you don't want it committed, or commit it to share context across machines.

---

Requirements

• Claude Code installed
• Git repository
• React + TypeScript project
• Node.js for running tests (npx vitest or npx jest)

---

Works Best With