React + Node.js

When to invoke

• Atlas frameworks.web in {Next.js, Vite-React, Remix} AND frameworks.api in {Express, Fastify, Hono, NestJS, tRPC}.
• User asks about "frontend talks to backend", "auth flow", "session cookies", "ws upgrade", "file upload", or "SSR vs CSR".

Key conventions

1. Contract choice — pick once, document in an ADR.
   • tRPC when both ends are TS and shipped together (monorepo) → end-to-end types, no codegen.
   • REST + OpenAPI when the backend has non-TS clients, or you want CDN cache + standard tooling. Generate the TS client from the spec.
   • GraphQL only when the client genuinely composes multiple resources per view (rare) — otherwise it's overhead.
2. Auth: JWT (short access) + rotating refresh, both in httpOnly; Secure; SameSite=Lax cookies. Never store tokens in localStorage. Refresh rotation: server invalidates the old refresh token on use; reuse → revoke all sessions for that family.
3. CSRF: SameSite=Lax covers most. Add a double-submit token if you allow SameSite=None (cross-site SPA → API). Use the framework's CSRF middleware (@fastify/csrf-protection, csurf is unmaintained — use csrf-csrf).
4. File uploads: stream, don't buffer. Use multer (Express) / @fastify/multipart with attachFieldsToBody: false → stream to S3/disk. Reject > N MB at the proxy (nginx/CloudFront), not in app. Validate MIME by reading magic bytes (file-type), not the Content-Type header.
5. REST → WebSocket upgrade: keep the HTTP server, attach ws (or socket.io) on the same port via the upgrade event. Authenticate the WS handshake by reading the same session cookie — never put the JWT in the query string (it ends up in access logs).
6. SSR vs CSR: SSR (Next.js / Remix) by default for content-heavy / SEO-sensitive pages. CSR (Vite-React SPA) when it's an internal tool or fully gated app. Don't bolt SSR onto a finished Vite SPA — migrate to a framework that has it.
7. Backend framework choice:
   • Hono for edge runtimes (Cloudflare Workers, Bun, Deno) — Web-standard Request/Response.
   • Fastify for high-throughput Node — schema-first, faster than Express, plugin model.
   • Express when there's an existing ecosystem you must reuse. New code: prefer Hono or Fastify.
   • NestJS only if your team genuinely wants Angular-style DI/decorators on the server.
8. Shared types: a packages/shared/ (or apps/api/contracts/) folder exports types consumed by both ends. With tRPC, this is free. With REST, generate from OpenAPI.

Canonical structure (monorepo, pnpm + turbo)

apps/
  web/             # React (Vite or Next.js)
  api/             # Node (Fastify or Hono)
    src/
      routes/      # one file per resource
      plugins/     # auth, cors, rate-limit
      lib/db.ts    # Prisma / Drizzle client
      lib/auth.ts  # JWT signing, cookie helpers
      ws/          # socket handlers
      server.ts    # entrypoint
packages/
  shared/          # zod schemas, types, error codes
  ui/              # if shared components
turbo.json
pnpm-workspace.yaml

Common pitfalls

1. JWT in localStorage — exfiltrated by any XSS. Always httpOnly cookie.
2. No refresh rotation — refresh tokens long-lived + non-rotating → one leak = forever access. Rotate on every use, detect reuse, revoke the family.
3. CORS too permissive in dev leaks to prod. Access-Control-Allow-Origin: * with credentials is rejected by browsers — but devs often set both to silence the error. Explicit allowlist, env-driven.
4. Multipart body parser on every route. Mount it only on the upload route. Otherwise every POST allocates buffers.
5. WS auth race: client connects before the cookie is set. Solve by gating the WS connection on a successful /me REST call, not on app boot.

References

• tRPC: https://trpc.io
• OWASP JWT cheat sheet: https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html
• Refresh-token rotation: https://auth0.com/docs/secure/tokens/refresh-tokens/refresh-token-rotation
• Fastify: https://fastify.dev
• Hono: https://hono.dev
• ws upgrade: https://github.com/websockets/ws#external-https-server

Hello world (login → ws upgrade)

// apps/api/src/routes/auth.ts (Fastify)
app.post('/login', { schema: { body: LoginSchema } }, async (req, reply) => {
  const user = await verify(req.body)
  const access = signAccess({ sub: user.id }, '15m')
  const refresh = await issueRefresh(user.id)   // rotates a family id
  reply
    .setCookie('access',  access,  { httpOnly: true, secure: true, sameSite: 'lax', path: '/' })
    .setCookie('refresh', refresh, { httpOnly: true, secure: true, sameSite: 'lax', path: '/auth/refresh' })
    .send({ ok: true })
})

// apps/api/src/ws/index.ts
server.on('upgrade', async (req, sock, head) => {
  const user = await userFromCookie(req.headers.cookie)
  if (!user) return sock.destroy()
  wss.handleUpgrade(req, sock, head, ws => wss.emit('connection', ws, user))
})