Skip to content

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.

  • Components: PascalCase (UserProfile.tsx)
  • Hooks: use prefix (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)
  • 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
  • Data fetching: Server Components + fetch with 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; ban any, @ts-ignore and as 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-eslint and next build are verified to work with it. Cloudflare tsrs may be the default --noEmit fast 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 uses TYPECHECKER=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-development resources/typescript-standards.md § “AI-Authored Code and Toolchain”
  • src/app/ — routes and layouts (Next.js App Router)
  • src/components/ — shared UI components
  • src/lib/ — utilities, helpers, shared logic
  • src/server/ — server-only code (DB, auth, API)
  • src/types/ — shared TypeScript types