code-conventions-web
Code Conventions — Web / TypeScript / Node.js
Section titled “Code Conventions — Web / TypeScript / Node.js”Extends core code-conventions.md. Web-specific patterns.
Naming
Section titled “Naming”- Components: PascalCase (
UserProfile.tsx) - Hooks:
useprefix (useAuth,useFormValidation) - Utils/helpers: camelCase (
formatDate,parseQuery) - API routes: kebab-case (
/api/user-profile) - CSS classes: kebab-case with BEM or Tailwind utility
- Env vars: SCREAMING_SNAKE_CASE (
DATABASE_URL)
Architecture
Section titled “Architecture”- Prefer Server Components by default (Next.js App Router)
- Client Components only when needed (
"use client"directive) - Co-locate components with their styles, tests, and types
- Use barrel exports (
index.ts) only at module boundaries, not within - Dependency injection via React Context or module-level singletons
Patterns
Section titled “Patterns”- Data fetching: Server Components +
fetchwith caching, or TanStack Query for client - Forms: Server Actions or TanStack Form — avoid uncontrolled forms
- State: URL state first, then React state, then global store (last resort)
- Error handling: Error Boundaries for UI, try/catch for server, Result types for utils
- Auth: middleware-first validation, never trust client-side auth checks alone
TypeScript, Not JavaScript (AI-authored code)
Section titled “TypeScript, Not JavaScript (AI-authored code)”- Write TypeScript, never plain JS: with no human code review the compiler is the first reviewer and a JS mistake only surfaces at runtime
strict: true; banany,@ts-ignoreandas unknown as X(lint + CI fail): a silenced type error is an unreviewed bug- Validate untrusted runtime data (HTTP, DB rows, webhooks) with a schema such as Zod: types vanish at runtime. Types never prove behavior, tests still decide
- Compiler: use the official native TS 7 compiler for typecheck/build once
ts-jest,typescript-eslintandnext buildare verified to work with it. Cloudflaretsrsmay be the default--noEmitfast pass only with the official compiler confirming every red; the emit build runs the same front door (tsc re-runs any red and its verdict wins), and release validation usesTYPECHECKER=tsc. Pin tsrs exact and re-run a parity check on every bump (it is 0.x beta, parity proven on one sample, known false positives). Detail:t1k-web-frontend-developmentresources/typescript-standards.md§ “AI-Authored Code and Toolchain”
File Organization
Section titled “File Organization”src/app/— routes and layouts (Next.js App Router)src/components/— shared UI componentssrc/lib/— utilities, helpers, shared logicsrc/server/— server-only code (DB, auth, API)src/types/— shared TypeScript types