@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/docs/plans/2026-02-23-nextjs-standards-design.md

@@ -0,0 +1,149 @@
+# Next.js Standards Package — Design Document
+
+**Date:** 2026-02-23
+**Status:** Approved
+
+---
+
+## Goal
+
+Add a comprehensive Next.js standards package to morph-spec-framework, bringing Next.js coverage from ~15% to parity with .NET for the primary use case: **Next.js frontend + .NET API backend**, deployed on EasyPanel (VPS/Docker).
+
+## Stack (Locked)
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | Next.js App Router |
+| UI Components | shadcn/ui |
+| Styling | Tailwind CSS |
+| Server state | TanStack Query (client) + Server Components (initial fetch) |
+| Forms | react-hook-form + Zod |
+| Deployment | Docker multi-stage build → EasyPanel (VPS) |
+| Language | TypeScript (strict mode) |
+
+---
+
+## Project Structure Convention
+
+Feature-based with shared core:
+
+```
+src/
+├── app/                          # Next.js App Router — routes only
+├── features/
+│   ├── {feature}/
+│   │   ├── components/           # feature-specific components
+│   │   ├── hooks/                # TanStack Query hooks for this feature
+│   │   ├── types/
+│   │   │   ├── {feature}.types.ts
+│   │   │   └── {feature}.schemas.ts   # Zod schemas → z.infer<> types
+│   │   └── index.ts              # public API of the feature
+├── components/
+│   ├── ui/                       # shadcn/ui primitives — never edit directly
+│   └── {shared-component}.tsx    # composed shared components (no business logic)
+├── hooks/                        # shared utility hooks only (no API calls)
+├── lib/
+│   ├── api-client.ts             # typed fetch wrapper for .NET API
+│   └── query-client.ts           # TanStack Query client config
+├── types/
+│   ├── api.ts                    # shared API shapes: PaginatedResponse<T>, ApiError
+│   └── env.d.ts
+└── env.mjs                       # Zod-validated env vars
+```
+
+---
+
+## Naming Conventions (Locked)
+
+| Artifact | Convention | Example |
+|----------|-----------|---------|
+| Component files | kebab-case | `user-card.tsx` |
+| Component exports | PascalCase | `export function UserCard()` |
+| Hook files | kebab-case with `use-` prefix | `use-create-user.ts` |
+| Hook exports | camelCase with `use` prefix | `export function useCreateUser()` |
+| Type files | kebab-case with `.types.ts` | `user.types.ts` |
+| Schema files | kebab-case with `.schemas.ts` | `user.schemas.ts` |
+| Feature folders | kebab-case | `features/user-management/` |
+| Page files | Next.js conventions | `page.tsx`, `layout.tsx`, `loading.tsx` |
+
+---
+
+## Component Hierarchy Rules
+
+1. **`components/ui/`** — shadcn/ui CLI output. Never edit. Customize by wrapping.
+2. **`components/`** — Composed shared components. No API calls, no feature imports, no business logic.
+3. **`features/*/components/`** — Feature-scoped. May use `components/` but never import from another feature's `components/`.
+
+---
+
+## Deliverables (~20 artifacts)
+
+### 1. Standards Files (8) — `framework/standards/frontend/nextjs/`
+
+| File | Scope |
+|------|-------|
+| `app-router.md` | Folder structure, file conventions, Server vs Client component decision |
+| `components.md` | Three-tier hierarchy, naming rules, reuse rules |
+| `data-fetching.md` | Server Components for initial fetch, TanStack Query patterns, query key conventions |
+| `forms.md` | react-hook-form + Zod patterns, schema co-location, shadcn Form wiring |
+| `state-management.md` | Server Components vs TanStack Query vs Context — escalation rules |
+| `naming-conventions.md` | Complete naming reference for files, exports, hooks, schemas, folders |
+| `project-structure.md` | Full canonical folder tree with examples |
+| `testing.md` | Jest + Testing Library, MSW for API mocking, co-location conventions |
+
+### 2. Rule File (1) — `framework/rules/nextjs-standards.md`
+
+Path-scoped to `**/*.tsx`, `**/*.ts` (excluding `**/*.cs`). References the 8 standards above. Installed to `.claude/rules/` during `morph-spec init`/`update`.
+
+### 3. Validator (1) — `src/lib/validators/nextjs/next-component-validator.js`
+
+Checks:
+- `'use client'` used without actual interactivity (useState, useEffect, event handlers)
+- `useState`/`useEffect` present without `'use client'` directive
+- Component file names are kebab-case
+- No `fetch('/api/...')` in Server Components (should call .NET API base URL)
+
+### 4. Templates (6) — `framework/templates/frontend/nextjs/`
+
+| File | Generates |
+|------|-----------|
+| `page.tsx.hbs` | App Router page with Server Component data fetch |
+| `client-component.tsx.hbs` | Client Component with TanStack Query + shadcn/ui |
+| `feature-form.tsx.hbs` | react-hook-form + Zod + shadcn Form |
+| `env.mjs.hbs` | Zod-validated environment variables |
+| `tsconfig.json.hbs` | Strict TypeScript config with path aliases |
+| `Dockerfile.nextjs.hbs` | Multi-stage production build for EasyPanel |
+
+### 5. Enhanced nextjs-expert Agent (1) — `framework/agents/frontend/nextjs-expert.md`
+
+Update to include:
+- Three-tier component hierarchy awareness
+- TanStack Query + react-hook-form/Zod as mandated patterns
+- kebab-case naming enforcement
+- EasyPanel/Docker deployment knowledge
+- Feature-based project structure guidance
+
+---
+
+## Standards Registry
+
+After adding 8 new standards files, regenerate `framework/standards/STANDARDS.json`:
+```bash
+node scripts/generate-standards-registry.js
+```
+
+---
+
+## Rules Installer
+
+The new `nextjs-standards.md` rule must be added to `src/commands/project/init.js`'s rules copy step (already copies `framework/rules/` → `.claude/rules/`). No code change needed — just adding the file is sufficient.
+
+---
+
+## Out of Scope
+
+- Next.js Route Handlers as backend (project uses .NET API)
+- SWR (TanStack Query is the standard)
+- Zustand/Redux (Server Components + TanStack Query covers state needs)
+- Vercel deployment (EasyPanel is the target)
+- React Native