React 19 Component Scaffolder

React 19 Component Scaffolder

Generate React 19/19.2 components, pages, hooks, and supporting files from parameterized templates. Every template enforces the patterns codified in the sibling react skill — refs as regular props (never forwardRef), Context rendered directly as provider (never .Provider), form actions with useActionState + useFormStatus, inline document metadata, useSyncExternalStore for external subscriptions, and YMNNAE-compliant hook bodies.

When to Apply

• Creating a new React component (Server, Client, or unspecified — defaults to Server)
• Adding a new route/page in a React 19 app
• Building a form that needs progressive enhancement, optimistic UI, or pending state
• Setting up a new Context provider with state + dispatch split
• Writing a custom hook that subscribes to external state or wraps async work
• Modeling complex state with a typed reducer
• Adding document metadata (<title>, <meta>, <link>) or resource hints (preload, preconnect, prefetchDNS)
• The user says "scaffold", "boilerplate", "generate", "new component", "new page", "new hook", or names any of the template types

Available Templates

All filenames are kebab-case; the exported React identifier ({Name}, use{Name}) is PascalCase / camelCase.

How to Use

1. Identify the template that matches the user's request. If ambiguous, ask. Default to function-component for unqualified "make me a component" requests. 2. Read the template at assets/templates/{name}.template. 3. Read the related conventions at references/conventions.md — every template emits code that obeys these conventions. 4. Collect parameters (see "Parameters" below). Ask the user only for parameters you cannot infer from context. 5. Substitute placeholders in the template. Every placeholder is wrapped in {curly_braces}. Empty placeholders (e.g., {additional_hooks} when there are none) collapse to empty string. 6. Write each output file using the Write tool. Use the path conventions in config.json (module_path, route_path). 7. Mention the conventions enforced so the user understands why the generated code looks the way it does (e.g., "I used ref as a prop rather than forwardRef because…").

Parameters

Common parameters (most templates accept these):

Template-specific parameters are documented in each template's leading comments.

Setup

On first use, populate config.json with project-specific paths so generated files land in the right place. The defaults assume a standard src/-rooted project. To override interactively:

• module_path — Where components live (e.g., src/components, app/_components)
• route_path — Where Server Component pages live (e.g., app/, src/routes/)
• hooks_path — Where custom hooks live (e.g., src/hooks)
• test_runner — vitest (default) or jest (changes the imports in test templates)

Conforming Existing Code (Multi-File Refactor)

When the user asks to conform, modernize, or align existing components with this skill's conventions across one or more files — not to generate new code — follow `references/_conform-algorithm.md` instead of going file-by-file.

Two non-negotiables from that doc:

1. Judgment over grep. Every convention is keyed off a syntactic marker (forwardRef, <Context.Provider>, react-helmet, onSubmit=, react-dom/test-utils). Grep finds the easy cases and misses the disguised ones — a manually drilled callback ref because the author dodged forwardRef, a bespoke useState({ pending, error }) that's useActionState without the name, a document.title hand-roll. Use grep for inventory and post-hoc completeness only, never as the primary detector. 2. Convention-major, not file-major. Load all target files first, then sweep one convention at a time across all files in priority order (refs/context/forms first, naming/imports last). Reports group by convention, surfacing cross-file clusters.

For brand-new scaffolds, skip this — go straight to a template.

React 19 Patterns This Skill Refuses to Generate

• forwardRef(...) wrappers — emits function Name({ ref, ...props }) instead
• <Context.Provider value={...}> — emits <Context value={...}> instead
• useFormState — emits useActionState instead
• onSubmit handlers for mutations — emits <form action={serverAction}> instead
• useRef<T>() without an argument — emits useRef<T>(null)
• useEffect for derived state, parent notification, or POST-on-state-change — refuses entirely (see conventions: State derivation)
• react-dom/test-utils — emits import { act } from '@testing-library/react' instead
• Manual <link rel="preload"> JSX — emits preload() from react-dom instead
• react-helmet / react-helmet-async — emits inline <title>/<meta>/<link> instead

Gotchas

See gotchas.md. Empty on first release — gotchas accumulate as the skill is used.

Related Skills

• `react` — Authoritative React 19 best-practices distillation (44 rules). The templates in this skill emit code that conforms to those rules.

React 19 Component Scaffolder

This curated skill mirrors SKILL.md. When maintaining it, keep templates aligned with React 19 patterns and avoid reintroducing deprecated React 18 APIs.

Gotchas

No known gotchas yet. Add entries here when scaffolding edge cases bite — be specific about what failed and what unblocked it.

Template

### {Short title — the symptom or the surprise}

{1-3 sentences describing what went wrong.}
Fix: {What unblocked it.}
Added: {YYYY-MM-DD}

Conform Algorithm — Bringing Existing Code In Line With These Conventions

Use this when the user asks to conform, modernize, or align existing components with this skill's conventions across one or more files (e.g. "make these match our scaffolded shape", "modernize this folder to the React 19 conventions", "audit this PR against our scaffolding rules").

For brand-new code, ignore this doc — go directly to a template. This algorithm exists for the retrofit case, where templates can't be used directly.

---

Principle 1 — Judgment over grep

Every convention in `conventions.md` is anchored to a syntactic marker (forwardRef, <Context.Provider>, react-helmet, e.preventDefault(), react-dom/test-utils). Those markers are easy to grep for and easy to miss the point of.

The decision rule for every convention is: "Does this code break the convention, in spirit?" — not "Does this string appear?"

Use grep/AST only to:

• Take inventory at the start (count files, list components, list templates that would apply)
• As a post-hoc completeness check after judgment-based review (e.g. confirm zero remaining forwardRef after refactor)

Never use grep as the primary detector for a convention violation. The judgment-based reads catch the disguised cases.

---

Principle 2 — Convention-major sweep, not file-major

For N files against 12 conventions, the natural reflex is file-major (walk each file, check all 12 conventions). It fails the same way it fails for the react skill: late files and low-priority conventions get silently skipped, and cross-file clusters stay invisible.

Do this instead — convention-major:

1. Load all target files into context up front (read them all before starting).
2. For each convention in conventions.md, in priority order (see below):
     a. State the convention's pattern in one sentence (the intent, not the marker).
     b. Sweep every applicable file simultaneously, looking for breaks of that pattern.
     c. Record findings grouped by convention, with file:line references.
3. After all conventions are swept, present findings ordered by convention × severity.

Convention priority order

conventions.md lists conventions topically. For a sweep, walk them in this priority:

1. Refs as regular prop, not `forwardRef` — HIGH (deprecated path; codemod available) 2. Context: `<Context value={...}>`, not `.Provider` — HIGH (deprecated path) 3. Forms: server action, not `onSubmit` for mutations — HIGH (progressive enhancement; pending state correctness) 4. State derivation: render-time, not effects — HIGH (correctness — sync holes; covers a large surface) 5. `useRef<T>(null)` always pass initial value — MEDIUM (TS breaking change) 6. External subscriptions: `useSyncExternalStore`, not manual `useEffect` + listeners — MEDIUM (concurrent-safe) 7. Test imports: `act` from `react`/`@testing-library/react`, never `react-dom/test-utils` — MEDIUM (removed in 19) 8. Server-side validation, always — MEDIUM (security) 9. Server Components by default, Client by exception — MEDIUM (bundle size) 10. Exhaustive switches in reducers — LOW (catches a class of bugs at compile time) 11. Custom hook naming: `use{Verb}{Noun}` / `use{Noun}` — LOW (clarity) 12. File naming + import grouping — LOW (cosmetic, formatter-equivalent)

---

Procedure

Step 0 — Confirm the file set

Get the explicit list of files from the user. Don't sweep an unbounded directory.

Step 1 — Inventory pass

Read every file once. Tag each as:

• Component (Server or Client — note which)
• Custom hook module
• Reducer module
• Context provider
• Form / action module
• Test file
• Other

Use the tag set to filter applicable conventions per file (e.g. "Server-side validation" applies only to action modules; "Exhaustive switches in reducers" applies only to reducer modules).

Step 2 — Convention-major sweep

For each convention in the priority order above, do one pass over all applicable files. For each file, ask: "Does this code achieve the convention's intent, in spirit?"

When you find a break, record:

• File:line — exact location
• Pattern break — one sentence in the spirit of the convention ("this form uses e.preventDefault() + manual useState({ pending, error }) — the exact useActionState shape, without the name")
• Conform action — the concrete shape change needed (point to a template if one applies: e.g. "shape matches form-action.tsx.template — replace with that shape")

Step 3 — Report findings

Group by convention. Within a convention, group by file. Add a Cross-file observations subsection per convention when 2+ files share the same break.

Step 4 — Apply (optional)

When the user approves:

• Apply by convention, not by file — finish all of convention 1 across all files before starting convention 2.
• For mechanically-replaceable cases (<Context.Provider> → <Context>, forwardRef removal), prefer the official codemods and note them. Don't reinvent.
• After applying a convention, take an inventory pass to confirm no regressions.

---

What this algorithm refuses to do

• Sweep an unbounded directory — demand a scope.
• File-major reports — never emit findings as "## src/Foo.tsx — issues: …" headings. Always group by convention.
• Grep-only findings — read the surrounding 30 lines before declaring a break. Grep is the trigger, never the verdict.
• Cosmetic-only sweeps that look like refactors — <Context.Provider> → <Context> is a codemod. The skill-worthy conforms are the shape changes (form refactors to useActionState, derived state moved to render, external subscriptions to useSyncExternalStore).

---

Quick sanity check before reporting

• Did I sweep every applicable convention against every applicable file?
• For each finding, is the evidence holistic (I read the surrounding code) or just a keyword match?
• Did I surface cross-file clusters where they exist?
• Did I propose a template (or codemod) where one fits, instead of hand-writing the shape?
• If a convention had zero findings, did I say so explicitly?

React 19 Scaffolding Conventions

These are the conventions every template enforces. Each one is here because not following it has caused real problems — the rationale matters more than the rule.

Placeholder substitution rules

Templates use {placeholder_name} syntax. The full placeholder reference for each template lives in its header comment block — read it before substituting. General rules:

• Single token ({Name}, {name_kebab}): expands to a single identifier with no surrounding whitespace.
• Block content ({prop_definitions}, {action_test_cases}, {content_body}): expands to one or more complete lines, each with its own trailing \n. Indent inside the block matches the position of the placeholder.
• Comma-prefixed lists ({additional_react_hooks}, {optimistic_import}): expand to , item1, item2 when present, empty string when absent. Templates expect the leading comma.
• Optional lines ({with_ref_prop}, {with_children_prop}): expand to a complete line including its \n, or empty string. Two consecutive optional lines safely collapse to nothing.
• Optional imports ({additional_type_imports}, {reducer_import}): expand to zero or more full import ... lines, each ending in \n, or empty string.

When a placeholder is absent, substitute the empty string — never leave the literal {...} in the output.

---

File naming: kebab-case files, PascalCase components

Files use kebab-case (user-card.tsx); the exported React component uses PascalCase (UserCard).

Why: macOS is case-insensitive by default; Linux CI is case-sensitive. Mixed-case filenames cause "works on my machine, fails in CI" bugs. The kebab-case file / PascalCase component split keeps the component identity readable in JSX while staying portable on disk.

Exception: Next.js route files (page.tsx, layout.tsx, loading.tsx, error.tsx) keep their framework-mandated names.

Refs: regular prop, never forwardRef

Templates emit:

interface InputProps {
  ref?: Ref<HTMLInputElement>
  placeholder?: string
}
function Input({ ref, placeholder }: InputProps) { /* ... */ }

Not:

const Input = forwardRef<HTMLInputElement, InputProps>(/* ... */)

Why: React 19 made ref a regular prop on function components. forwardRef will be deprecated in a future major. New code using forwardRef is born deprecated. The codemod path (npx codemod@latest react/19/replace-forwardRef) goes one direction — we generate code that doesn't need it.

Context: <Context value={...}>, never .Provider

Templates emit:

<UserContext value={user}>{children}</UserContext>

Not:

<UserContext.Provider value={user}>{children}</UserContext.Provider>

Why: Same as refs — .Provider is the legacy syntax. React 19 rewrote the React developer surface to make Context directly renderable.

useRef<T>(null) — always pass an initial value

Templates emit:

const inputRef = useRef<HTMLInputElement>(null)

Not:

const inputRef = useRef<HTMLInputElement>()

Why: React 19 made the argument required (TypeScript breaking change). The single-argument form is also clearer — readers see immediately what the ref starts as.

Forms: server action, never onSubmit for mutations

Templates emit:

<form action={createUser}>

Not:

<form onSubmit={(e) => { e.preventDefault(); createUser(/* ... */) }}>

Why: Form actions work without JavaScript (progressive enhancement). They eliminate preventDefault boilerplate. They integrate with useActionState, useFormStatus, and useOptimistic for pending and optimistic UI. Reaching for onSubmit regresses to React 18.

Exception: Client-only forms with no server (e.g., a search box driving a router push). Even there, <form action={fn}> with a client-side function is the cleaner pattern.

Server Components by default, Client Components by exception

Templates default to no 'use client'. The client island template (client-island.tsx.template) is the only one that emits the directive, and only because that's its purpose.

Why: 'use client' boundaries become bundle inclusions. The lower in the tree the boundary lives, the less JavaScript ships. The default of "Server Component unless we explicitly need state, event handlers, or browser APIs" produces smaller bundles.

Test imports: act from react, never react-dom/test-utils

Test templates emit:

import { act } from '@testing-library/react'
// or, when needed standalone:
import { act } from 'react'

Why: react-dom/test-utils was removed in React 19. The codemod (npx codemod@latest react/19/replace-act-import) moves to react. New test files should never grow that import.

Custom hook naming: use{Verb}{Noun} or use{Noun}

Templates emit useToggleTheme, useDebouncedValue, useUserPreferences — verbs when the hook drives a behavior, plain noun when it exposes state.

Why: Disambiguates side-effecting hooks from pure-read hooks. useTheme() reads; useToggleTheme() toggles. Mixing the two in the same code becomes confusing.

State derivation: render-time, not effects

The custom-hook and reducer templates have NO useEffect calls for derived state. If the value can be computed from props/state, it is — const fullName = ${first} ${last}``.

Why: Effects for derived state cause extra render passes and create sync holes (state can be stale between updates). You Might Not Need an Effect catalogues a dozen variants of this anti-pattern. We refuse to generate any of them.

External subscriptions: useSyncExternalStore, not manual useEffect + listeners

The custom-hook template offers a subscribe_target parameter; when set, it generates a useSyncExternalStore skeleton, not an effect-based subscription.

Why: useSyncExternalStore is tearing-free in concurrent rendering, SSR-safe via the third argument, and has the cleanup wired in for you. Manual useEffect + addEventListener is a pre-React-18 pattern.

Exhaustive switches in reducers

The reducer template ends every switch with:

default:
  return assertNever(action)

Why: Adding a new action variant without handling it becomes a TypeScript error rather than a silent runtime fall-through. The cost is one helper function; the value is catching unhandled actions at compile time.

Server-side validation, always

The form-action template's actions.ts always calls schema.safeParse(raw) on the server. Client-side validation is optional cosmetic; server-side validation is non-negotiable.

Why: Client-side validation can be bypassed (disable JS, edit the DOM, hit the action directly). The server is the only place where validation is enforceable. Skipping server validation is a security bug, not a style choice.

Imports: framework → external → internal → relative, blank line between groups

Templates lay out imports in four blocks separated by blank lines:

import { useState } from 'react'              // framework
import { useFormStatus } from 'react-dom'

import { z } from 'zod'                       // external

import { db } from '@/lib/db'                 // internal alias

import { schema } from './schema'             // relative

Why: Auto-formatters (Biome, Prettier with plugins, ESLint import/order) all agree on this grouping. Keeping the convention prevents merge churn from formatter disagreements. The visual grouping also makes "is this a third-party import?" obvious at a glance.