Production — Cheat Sheet

The Build, and What It Produces

npm run build

// 1. Compile          TypeScript and JSX -> JavaScript (SWC)
// 2. Lint and typecheck (unless disabled)
// 3. Bundle           client chunks, per route
// 4. Prerender        run every static page and write HTML
// 5. Optimise         minify, tree-shake, generate the manifests

// Phase 4 is the one that surprises people: your page code RUNS at
// build time. So a build fails if a static page:
//   queries a database that is not reachable from CI
//   reads an environment variable that is not set in CI
//   calls an API that is down
// "Error occurred prerendering page /problems" means your code threw
// during the build, not that the route is misconfigured.

// Skipping checks in the build is a trap worth naming:
// next.config.js
typescript: { ignoreBuildErrors: true }     // do not
eslint: { ignoreDuringBuilds: true }        // do not
// Both hide the failure until runtime. Run tsc and eslint as separate
// CI steps if the build is slow, but do not silence them.

Deploying — Vercel and Self-Hosting

// git push -> build -> deploy. Nothing to configure for the common case.
// Every branch gets a preview URL; production is instant to roll back
// because previous builds stay served.

// What is handled for you:
//   a global CDN for static assets and prerendered pages
//   each route as a serverless or edge function, scaled to zero
//   image optimisation on demand
//   the ISR cache, shared across instances
//   middleware at the edge

// The costs that surprise teams:
//   function invocations and duration — a dynamic route is billed per
//     request, so an accidental ○ -> ƒ regression shows up on the bill
//   image transformations — billed per source image
//   bandwidth
// A static-heavy content site is cheap here. A dynamic-heavy app with
// large traffic is where people start comparing.

// vercel.json for the things that are not automatic:
{
  "regions": ["bom1"],                       // put functions near the DB
  "crons": [{ "path": "/api/cron/digest", "schedule": "0 3 * * *" }]
}
// Region matters more than it sounds: functions in Washington talking
// to a database in Mumbai pay that round trip on every query.

Node and Edge Runtimes

export const runtime = 'nodejs'      // the default
export const runtime = 'edge'

// EDGE
//   + near-zero cold start
//   + runs in a location near the user
//   + cheaper per invocation
//   - Web APIs only: no fs, no net, no most Node built-ins
//   - no TCP, so no Postgres/MySQL client — HTTP-based drivers only
//   - no native modules (bcrypt, sharp, canvas)
//   - a bundle size limit, typically a few MB
//   - shorter execution limits

// NODE
//   + everything: any npm package, any database driver
//   + longer execution, larger bundles
//   - cold starts
//   - runs in one region

// The trap: an edge function near the user that queries a database
// in one region pays the distance on every query. Being close to the
// user only helps if the work is self-contained — a redirect, a
// header, a cached lookup, a token check.

// Middleware is always edge, which is why it cannot read a session
// from the database.

Performance — Bundles and Core Web Vitals

npm i -D @next/bundle-analyzer
// next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})
module.exports = withBundleAnalyzer(nextConfig)

ANALYZE=true npm run build

// What it usually shows, in order of frequency:
//   a date library (moment) in the shared chunk
//   an icon set imported as a barrel
//   a chart or editor library on a page most people never open
//   two copies of a library from mismatched versions
//   a client component pulling in a server-side dependency

// Split what is heavy and rarely used:
const Editor = dynamic(() => import('@/components/Editor'), {
  ssr: false,                       // it touches window
  loading: () => <EditorSkeleton />,
})

// Import per icon, never the barrel:
import { Search } from 'lucide-react'         // one icon
import * as Icons from 'lucide-react'         // the whole set

// And the Next-specific one: check whether the code needs to be on
// the client at all. Moving a component back to the server removes
// it from the bundle entirely, which beats any splitting.

Monitoring and Debugging in Production

// Server errors are redacted in production: the client sees a
// generic message and a digest, and the full stack is in your logs
// under that digest. Show the digest, or the user has nothing to
// quote to support.
export default function Error({ error }) {
  return <p>Something went wrong. Reference: {error.digest}</p>
}

// Capture both sides. Sentry's Next SDK wires server components,
// actions, route handlers and the browser:
// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') await import('./sentry.server.config')
  if (process.env.NEXT_RUNTIME === 'edge')   await import('./sentry.edge.config')
}
export const onRequestError = Sentry.captureRequestError

// What client-side capture catches that server logs never will:
//   hydration mismatches
//   chunk load failures after a deploy
//   errors in event handlers, which no boundary catches
//   failures on browsers you do not test

// A global handler for unhandled rejections, so they are at least
// counted:
window.addEventListener('unhandledrejection', (e) => report(e.reason))

Testing a Next Application

// UNIT — plain functions. The easiest and highest-value tests, and
// the App Router pushes more logic here than the Pages Router did.
import { calculateReadiness } from '@/lib/scoring'
expect(calculateReadiness(attempts)).toEqual({ score: 26 })

// Data functions with the database mocked, or against a test DB:
vi.mock('@/lib/db')
expect(await getProblemsForUser()).toHaveLength(3)

// COMPONENT (Vitest + Testing Library) — client components only
import { render, screen } from '@testing-library/react'
render(<ProblemFilters onChange={fn} />)         // 'use client'

// Async SERVER components do not render in Testing Library. You can
// await the function and inspect the returned element, but you are
// then testing an object, not behaviour:
const el = await ProblemsPage({ params: Promise.resolve({ slug: 'x' }) })
// Possible; rarely worth it.

// E2E (Playwright) — anything involving the server: server
// components, server actions, middleware, auth, redirects, caching.
// This is where the App Router's real behaviour is testable at all.

next.config and Build Configuration

// next.config.js
/** @type {import('next').NextConfig} */
module.exports = {
  reactStrictMode: true,

  images: {
    remotePatterns: [
      { protocol: 'https', hostname: '**.supabase.co', pathname: '/storage/**' },
    ],
    formats: ['image/avif', 'image/webp'],
  },

  async redirects() {
    return [
      // moved 2026-08 — keep until the old links stop appearing in logs
      { source: '/old-problems', destination: '/dsa/problems', permanent: true },
    ]
  },

  async headers() {
    return [{ source: '/:path*', headers: SECURITY_HEADERS }]
  },

  async rewrites() {
    // proxy the API so cookies stay first-party
    return [{ source: '/api/:path*', destination: `${process.env.API_URL}/:path*` }]
  },

  // Trim large barrel-file libraries
  experimental: { optimizePackageImports: ['lucide-react', 'date-fns'] },
}

// redirect  — the URL changes, the browser sees the new one (301/308)
// rewrite   — the URL stays, different content is served (a proxy)

Caching at the Edge in Production

// browser cache -> CDN -> Next's caches -> your data

// What Next emits by default:
//   a static page       s-maxage long, stale-while-revalidate
//   an ISR page         s-maxage = your revalidate, SWR
//   a dynamic page      no-store — never cached anywhere
//   /_next/static/*     immutable, one year (filenames are hashed)

// s-maxage applies to shared caches (the CDN); max-age applies to
// the browser. The distinction matters:
Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400, max-age=0
// -> the CDN caches for an hour and can serve stale for a day while
//    refreshing; the browser always revalidates.
// That combination is usually what you want: purging the CDN then
// fixes a bad page for everyone, rather than waiting out browser
// caches you cannot reach.

// In a route handler you set it yourself:
return NextResponse.json(data, {
  headers: { 'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=300' },
})
// A route handler with no header and no revalidate is uncached in
// Next 15 and cached in 14 — be explicit.

Migrating from the Pages Router

// pages/_app.js          -> app/layout.tsx (root layout)
// pages/_document.js     -> app/layout.tsx (html and body live there)
// pages/index.js         -> app/page.tsx
// pages/problems/[slug].js -> app/problems/[slug]/page.tsx
// pages/api/x.js         -> app/api/x/route.ts
// pages/404.js           -> app/not-found.tsx
// pages/500.js           -> app/error.tsx / global-error.tsx

// getServerSideProps -> just await in the component
export async function getServerSideProps({ params }) {          // before
  const problem = await getProblem(params.slug)
  return { props: { problem } }
}
export default async function Page({ params }) {                 // after
  const problem = await getProblem((await params).slug)
  return <Article problem={problem} />
}

// getStaticProps + revalidate -> export const revalidate
// getStaticPaths             -> generateStaticParams
// next/head                  -> the metadata export
// next/router                -> next/navigation (different API!)
//   router.query   -> useParams / useSearchParams
//   router.pathname-> usePathname
//   router.events  -> gone; derive from usePathname

// The import path is the trap: next/router silently does nothing
// useful in app/, and the error is not obvious.