contextarch

Opinionated Next.js + TypeScript + Tailwind + Prisma rules. App Router, Server Components by default, typed Server Actions.

# Next.js 15 + TypeScript + Tailwind + Prisma                                                                                                                                       
                                                                     
  ## How to work in this repo
  - Do what was asked; don't refactor adjacent code or add speculative abstractions.
  - Before editing, read the file and its direct callers.                                                                                                                             
  - Ask one clarifying question when ambiguous rather than guessing.                                                                                                                  
                                                                                                                                                                                      
  ## TypeScript                                                                                                                                                                       
  - Prefer `type` for object shapes; `interface` only when extending third-party types.
  - Never `any` — use `unknown` and narrow, or write a proper type.                                                                                                                   
  - No non-null assertions (`!`) except in tests or right after a type guard.                                                                                                         
  - `import type { ... }` for type-only imports.
  - Prefer discriminated unions over enums.                                                                                                                                           
                                                                     
  ## Next.js (App Router)                                                                                                                                                             
  - App Router (`app/`) only. Pages Router in legacy projects only.  
  - Server Components by default. Add `"use client"` only when you need state, effects, or browser APIs.                                                                              
  - Data fetching lives in Server Components or Route Handlers — never `useEffect`.                                                                                                   
  - Server Actions for mutations; validate every input with Zod before doing work.                                                                                                    
  - Use `loading.tsx` and `error.tsx` boundaries. Stream with `<Suspense>` where it helps.                                                                                            
  - `next/image` for images, `next/font` for fonts. Never `<img>` or Google Fonts `<link>`.
  - Cache with `fetch` options (`next: { revalidate }`, `cache: 'force-cache'`) — don't reinvent.                                                                                     
  - Metadata via `generateMetadata` or static `metadata` export. Not ad-hoc.                                                                                                          
  - Never put server-only secrets in client components — they leak into the bundle.                                                                                                   
                                                                                                                                                                                      
  ## React                                                                                                                                                                            
  - Function components only.                                                                                                                                                         
  - `useState` for local UI state, `useReducer` for multi-transition state, a store only for cross-tree state.
  - Memoize (`useMemo`, `useCallback`, `React.memo`) only when there's measured render cost.
  - Effects are for syncing with external systems; compute derived state in render.                                                                                                   
  - Keys on lists are stable IDs, never array indexes.                                                                                                                                
  - Buttons are `<button>`, links are `<a>`, inputs have labels.                                                                                                                      
                                                                                                                                                                                      
  ## Tailwind CSS                                                    
  - Utility classes; extract to components only when a class list repeats 3+ times.                                                                                                   
  - Use design tokens in `tailwind.config.ts` — no magic `#hex` in markup.                                                                                                            
  - Use `clsx` / `cn()` for conditional classes, not template-string concatenation.
                                                                                                                                                                                      
  ## Prisma                                                          
  - Schema is source of truth. Migrations via `prisma migrate`; never raw SQL drift.                                                                                                  
  - Select only the fields you need — don't return full rows to clients.                                                                                                              
  - Wrap multi-step mutations in `prisma.$transaction([...])`.
  - Singleton client in server code; don't instantiate `new PrismaClient()` per request.                                                                                              
                                                                                                                                                                                      
  ## Guardrails
  - Never commit secrets, API keys, or credentials.                                                                                                                                   
  - Don't invent dependencies — if a package isn't in the manifest, confirm before adding.                                                                                            
  - When a command fails, read the actual error. Don't retry blindly or use `--force`.
  - Prefer editing existing files over creating new ones.                                                                                                                             
  - If you touch public types or exported APIs, check every caller.  
                                                                                                                                                                                      
  ---                                                                
  Generated by `npx contextarch init` — https://contextarch.ai