Imported from Ridvan-bot/PPAgent (skills/fullstack-best-practices/SKILL.md). Install upstream with npx skills add Ridvan-bot/PPAgent --skill fullstack-best-practices. Copyright stays with the author.

Fullstack Best Practices

Apply when designing or reviewing fullstack applications (e.g. Next.js + API, React + Node, or similar).

API and Contract

• Define a clear API contract (REST or tRPC/GraphQL); document request/response shapes and error codes. Prefer OpenAPI or shared types (e.g. TypeScript types imported by frontend and backend).
• Use consistent HTTP semantics: GET idempotent and cacheable; POST for create; PUT/PATCH for update; appropriate status codes (200, 201, 400, 401, 404, 500).
• Version APIs when breaking changes are needed (path prefix or header); avoid breaking changes without a deprecation path.

Data Flow and Boundaries

• Fetch on the server when possible (RSC, getServerSideProps, route handlers) to avoid extra round-trips and expose less surface to the client.
• Pass only serializable data across the network and between server and client; avoid passing functions or class instances. Use DTOs or shared types for API boundaries.
• Validate and sanitize all input on the backend; never trust client-only validation for security or correctness.

Auth and Session

• Handle auth on the server (session, JWT validation, or provider callbacks); never rely only on client-side checks for protected resources.
• Use httpOnly, secure cookies for session when applicable; avoid storing tokens in localStorage for sensitive apps unless the pattern is explicit (e.g. B2B with short-lived tokens).
• Prefer established libraries (e.g. NextAuth, Better Auth, Passport) with secure defaults; document any custom auth flow.

Errors and Loading

• Return structured errors from the API (e.g. { error: { code, message } }); map to user-friendly messages on the frontend.
• Use loading and error boundaries (Suspense, error.tsx, toast) so the UI never shows raw stack traces or hangs indefinitely.
• Log errors and correlation ids on the server; avoid leaking internal details to the client.

Performance and Caching

• Use caching headers (ETag, Cache-Control) for public or stable data; invalidate or use short TTL where data changes often.
• Prefer one round-trip per view when possible (batch in API or use GraphQL/tRPC batching); avoid N+1 or waterfall requests from the client.
• Consider edge or CDN for static and semi-static content; keep sensitive or dynamic logic on the server.

Environment and Config

• Use env vars for API base URLs, feature flags, and keys; different values per environment (dev/staging/prod).
• Never expose server-only secrets to the client bundle; use server-side env or API routes to proxy sensitive calls.