@polymorphism-tech/morph-spec 4.7.2 → 4.8.4

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

@@ -1,149 +0,0 @@
-# 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