React Package Builder Skill

React Package Builder

Create decoupled, reusable React packages for the monorepo.

Workflow

Audit existing component for app-specific dependencies
Design props contract (see props-patterns.md)
Scaffold package structure (see package-structure.md)
Verify decoupling (see decoupling-checklist.md)
Create adapter in consuming app

Quick Start

# Create package directory
mkdir -p packages/<package-name>/src/{ui,hooks,engine,styles}

# Create package.json
cat > packages/<package-name>/package.json << 'EOF'
{
  "name": "@raamattu-nyt/<package-name>",
  "version": "1.0.0",
  "main": "src/index.ts",
  "peerDependencies": { "react": ">=18" }
}
EOF

Core Principles

| Principle | Implementation | |-----------|----------------| | No fetching | Data via props, callbacks for mutations | | No Supabase | Parent adapter handles DB | | No Auth | Parent provides auth context if needed | | No persistence | Parent saves progress/preferences | | Signals only | Emit callbacks, don't execute side effects |

Props Contract Template

interface ComponentProps {
  // ---- Content ----
  title: string;
  items: Item[];

  // ---- Index (controlled/uncontrolled) ----
  currentIndex?: number;
  defaultIndex?: number;
  onIndexChange?: (index: number, meta: { source: string }) => void;

  // ---- Signals (parent handles audio/media) ----
  onToggleAudio?: (enabled: boolean) => void;
  onVolumeChange?: (volume: number) => void;

  // ---- Lifecycle ----
  onExit?: () => void;
}

Cross-cutting learnings: See .claude/LEARNINGS.md → "React/TypeScript" section for useCallback deps, controlled component patterns, and infinite loop prevention.

References

package-structure.md — Directory layout, naming conventions
props-patterns.md — Controlled/uncontrolled, engine abstraction
decoupling-checklist.md — Verify no app dependencies

Agent Skills: React Package Builder

Install this agent skill to your local

Skill Files