The Senior Frontend Engineer's Field Guide: Building an Enterprise Next.js 16 and React 19 Application From Scratch

Every senior frontend interview eventually asks the same question in a different costume: "walk me through how you'd build this for real." Not a to-do list app — a route that needs to be fast for an anonymous visitor and correct for a logged-in one, a form that has to survive a replayed request, a cache that has to invalidate itself without taking the site down. The honest answer requires knowing what actually happens when you type next build, not what a blog post from eighteen months ago said happens.

This is that build, done for real. Every command below was actually run against Next.js 16.3.6 and React 19.2.8 — the exact versions create-next-app@latest installs today — with the output pasted verbatim, not reconstructed from memory. Where the framework's behaviour has changed recently enough that older material gets it wrong (and several load-bearing details have: middleware.ts has a new name, revalidateTag grew a second required argument, one of React's advertised security APIs doesn't exist in the package you actually install), that's called out explicitly, with the exact error message the compiler or the build produces when you get it wrong.

The scope is deliberately total: routing and rendering, the caching model, Server Actions and the attacks against them, authentication with public and private routes, data fetching, Core Web Vitals, and then the language-level material — TypeScript's type system, JavaScript's quirks, advanced CSS and Tailwind v4, DOM APIs — that a staff-level interview panel will pull on once the framework questions are exhausted. Work through it top to bottom over a few sittings and you will have both a working application and the vocabulary to defend every decision in it.

A note on versions before starting: Next.js ships fast, and a framework this actively developed will have moved again by the time you read this. Treat every version number here as "true as of the build transcript," not as a permanent fact — and treat the technique of checking (node_modules/next/dist/docs, the shipped .d.ts files, an actual tsc --noEmit) as the more durable skill than any single number.

Part 0 — Project setup, and what every configuration choice actually does

0.1 Scaffolding the project

Don't hand-write the initial file tree. create-next-app is maintained by the same team that maintains the framework, and it encodes the current defaults — which config file extension, which directory layout — more reliably than a tutorial does.

npx create-next-app@latest enterprise-app \
  --typescript \
  --eslint \
  --tailwind \
  --app \
  --turbopack \
  --no-src-dir \
  --import-alias "@/*" \
  --use-npm

What each flag actually controls, and why this build picks it:

Real installed versions from this exact command, run today:

$ npm ls next react react-dom
[email protected]
├─┬ [email protected]
│ ├── [email protected] deduped
│ └── [email protected] deduped
├─┬ [email protected]
│ └── [email protected] deduped
└── [email protected]

create-next-app also writes an AGENTS.md file into the project by default now — a short brief aimed at coding agents, not humans, describing the App Router conventions it just scaffolded. Leave it; it's a genuinely useful anchor if you later point an AI coding assistant at the repo, and deleting it changes nothing about how the app runs.

0.2 The generated package.json scripts — read them before you customise them

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "eslint"
}

Notice what's missing: no --turbopack flag anywhere, even though it was passed to create-next-app. That's not an oversight — it's the confirmation that Turbopack is the default bundler for both commands now, not an opt-in. Running next build with zero flags on this exact project prints:

$ npx next build
▲ Next.js 16.3.6 (Turbopack)
✓ Running next.config.ts took 68ms

  Creating an optimized production build ...
✓ Compiled successfully in 4.0s
  Running TypeScript ...
  Finished TypeScript in 1293ms ...
  Collecting page data using 5 workers ...
  Generating static pages using 5 workers (0/4) ...
✓ Generating static pages using 5 workers (4/4) in 215ms
  Finalizing page optimization ...

Route (app)
┌ ○ /
└ ○ /_not-found


ƒ Proxy (Middleware)

○  (Static)  prerendered as static content

The very first line self-reports (Turbopack). If you're coming from a Next.js 14 or 15 background where --turbopack was an opt-in flag you had to remember to pass to next dev (and where next build --turbopack was still experimental), unlearn that: as of 16, it's the only bundler a fresh project uses unless you deliberately opt back out to Webpack.

One more detail worth an interview-answer's worth of attention: the route table already prints ƒ Proxy (Middleware) in a project that has neither a proxy.ts nor a middleware.ts file yet. That's the framework's own build output using "Proxy" as the primary label with "Middleware" kept in parentheses for continuity — the rename goes all the way down into the tooling's own vocabulary, which is the first sign of how seriously to take the next section.

0.3 package.json dependencies, and the version drift a stale tutorial will hand you

A dependency block copied from an article — even a recent one — is a liability the moment a major version ships underneath it. Three packages in this build have moved a full major version in the last few months, and the difference isn't cosmetic:

{
  "dependencies": {
    "next": "16.3.6",
    "react": "^19.2.8",
    "react-dom": "^19.2.8",
    "@tanstack/react-query": "^5.103.2",
    "zod": "^4.6.5",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
    "tailwind-merge": "^2.5.4",
    "server-only": "^0.0.1"
  },
  "devDependencies": {
    "@types/node": "^22.8.0",
    "@types/react": "^19.3.0",
    "@types/react-dom": "^19.0.0",
    "@tailwindcss/postcss": "^4.3.3",
    "tailwindcss": "^4.3.3",
    "typescript": "^5.6.3"
  },
  "engines": {
    "node": ">=20.9.0"
  }
}

• Zod is on v4 (^4.6.5), not the ^3.23.8 you'll see quoted in older material. The object schema API — z.object, .safeParse, z.coerce.number(), .trim() — is unchanged, but ZodError.flatten() is deprecated in favour of the top-level z.flattenError(error), covered in Part 4. If you paste a v3-shaped error handler into a v4 project, it still runs (with a deprecation warning), which is exactly the kind of silently-stale code a senior engineer is expected to catch on review.
• @tanstack/react-query is on 5.103.2, still v5 (no v6 exists yet), but the recommended server/browser QueryClient singleton pattern changed under it — isServer as a bare import still works but is deprecated in favour of environmentManager.isServer(). Covered in Part 6.
• Tailwind is on v4, which is a CSS-first rewrite: there is no tailwind.config.js to write, and the PostCSS plugin package changed name from tailwindcss itself to @tailwindcss/postcss. Covered in Part 9.

Do not treat any dependency version as permanent. The one durable habit: before writing a line of code against a library, run npm view <package> version and read its actual changelog for the major version gap between what you remember and what's current.

0.4 Strict TypeScript configuration (tsconfig.json)

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "allowJs": false,
    "skipLibCheck": true,
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }],
    "paths": { "@/*": ["./*"] }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

An interviewer who asks "what does strict: true actually turn on" wants to see that you know it's a bundle, not one flag. Here's what each of the flags above actually catches, with the concrete bug:

• strict: true is shorthand for eight flags at once: strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitAny, noImplicitThis, alwaysStrict, and useUnknownInCatchVariables. Listing them individually below (as this config does) is redundant with strict: true but makes the intent explicit for a reader auditing the file — and lets you selectively relax one later without losing the rest.
• strictNullChecks — without it, const user: User = null type-checks. Every senior codebase has at least one Cannot read property 'x' of undefined postmortem this flag would have caught at compile time instead of in a Sentry alert.
• noUncheckedIndexedAccess — without it, const first = users[0] has type User, not User | undefined, even though users could be empty. This is the single most underrated strictness flag: it turns every array/object index access into an explicit | undefined, forcing a null check at the exact call site instead of three functions downstream.
• exactOptionalPropertyTypes — distinguishes { name?: string } (the key may be absent) from { name: string | undefined } (the key must be present, value may be undefined). Without this flag, obj.name = undefined silently satisfies an optional property type even when the surrounding code actually branches on 'name' in obj.
• noImplicitOverride — requires an explicit override keyword when a subclass method shadows a base class method. Catches the case where you rename a base method and a subclass override silently becomes a new, unrelated method instead of erroring.
• isolatedModules — required because Turbopack (like all modern single-file transpilers) compiles each file independently, without cross-file type information. It rejects TypeScript features that need whole-program analysis to erase correctly (const enum, ambiguous re-exports of types without export type).
• moduleResolution: "bundler" — tells TypeScript to resolve imports the way a bundler does (respecting exports maps in package.json, no mandatory file extensions) rather than the older node/node16 algorithms. Using anything else with a bundler this modern produces phantom "Cannot find module" errors for packages that only publish an exports map.
• plugins: [{ "name": "next" }] — enables the Next.js TypeScript plugin, which gives editor-level type-checking for entry-point conventions the compiler alone can't see: that page.tsx default-exports a component with the right prop shape, that a Server Action file only exports async functions, that metadata and generateMetadata aren't declared in the same file.

Verify the strictness is real, not decorative, with a quick empirical check: write a page with params: Promise<{ slug: string }> and read params.slug directly instead of awaiting it first.

// deliberately wrong
export default function Page({ params }: { params: Promise<{ slug: string }> }) {
  return <h1>{params.slug}</h1>;
}

$ npx tsc --noEmit
app/test/[slug]/page.tsx(2,27): error TS2339: Property 'slug' does not exist on type 'Promise<{ slug: string; }>'.

That's the compiler doing real work, not a lint suggestion — the build fails.

0.5 next.config.ts, and where its flags actually live

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  // Cache Components: explicit 'use cache' boundaries + Partial Prerendering
  cacheComponents: true,

  // Prefetch the static shell of a linked route ahead of navigation
  partialPrefetching: true,

  reactStrictMode: true,
  poweredByHeader: false,

  images: {
    formats: ['image/avif', 'image/webp'],
    remotePatterns: [{ protocol: 'https', hostname: 'images.unsplash.com' }],
  },

  experimental: {
    optimizePackageImports: ['lucide-react', '@tanstack/react-query'],
  },
};

export default nextConfig;

next.config.ts — a TypeScript config file, not .js or .mjs — is what create-next-app scaffolds by default for a TypeScript project, and Next.js transpiles and executes it directly at startup: every dev/build invocation logs ✓ Running next.config.ts took Nms, confirming there's no separate compile step or JS fallback involved.

Two flags here are worth being precise about, because their exact location in the config object is a real, checkable fact — not a style preference — and getting it wrong produces a working-but-wrong build with a deprecation warning instead of a clean error:

• cacheComponents is a top-level NextConfig key, not experimental.cacheComponents. The nested location is still accepted in 16.3.6 for migration purposes, but every build using it prints ⚠ experimental.cacheComponents has been moved to cacheComponents. Please update your next.config.ts file accordingly. This single flag is the on-switch for everything in Part 3 — the 'use cache' directive, cacheLife, cacheTag, and Partial Prerendering are all gated behind it. Without it, a 'use cache' function anywhere in the tree fails the build outright (shown in Part 3).
• partialPrefetching is also top-level, typed as boolean | 'unstable_eager', and distinct from an older, now-deprecated experimental.ppr flag that pre-16 material still references (that flag was folded directly into cacheComponents — there is no separate PPR on/off switch anymore). partialPrefetching instead controls how much of a route <Link prefetch> fetches ahead of a click, and it hard-requires cacheComponents: true — setting it alone, without cacheComponents, fails the build with Error: partialPrefetching requires cacheComponents to be enabled.

experimental.optimizePackageImports earns its experimental nesting honestly: the Next.js docs still mark it "not recommended for production" as of this build. What it does is rewrite a barrel import (import { Activity } from 'lucide-react') into a direct path import (lucide-react/dist/esm/icons/activity) at compile time, so the bundler doesn't have to parse every sibling export in the barrel file to tree-shake the one you used. Section 6.4 covers why barrel files are a bundle-size trap in the first place.

0.6 Request interception: proxy.ts, the renamed middleware.ts

If you've built a Next.js app before 16, this is the single highest-value fact to update: middleware.ts was renamed to proxy.ts in Next.js 16. Not superseded by a different mechanism — literally renamed, same responsibilities, same place in the request lifecycle (it runs before routing, rendering, or any Server Component execution), same NextRequest/NextResponse API, same config.matcher shape.

// proxy.ts
import { NextResponse, type NextRequest } from 'next/server';

const PUBLIC_FILE = /\.(.*)$/;

export function proxy(request: NextRequest): NextResponse {
  const { pathname } = request.nextUrl;

  if (
    pathname.startsWith('/_next') ||
    pathname.startsWith('/api/auth') ||
    PUBLIC_FILE.test(pathname)
  ) {
    return NextResponse.next();
  }

  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-forwarded-host', request.headers.get('host') ?? '');
  requestHeaders.set('x-origin-path', pathname);

  const response = NextResponse.next({ request: { headers: requestHeaders } });

  response.headers.set('X-Frame-Options', 'DENY');
  response.headers.set('X-Content-Type-Options', 'nosniff');
  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
  response.headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');

  return response;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

Don't take the rename on faith — three real dev-server runs settle exactly how Next.js resolves the two filenames when both exist, and the answer is not "one silently wins":

proxy.ts alone — it runs. A request to / logs PROXY_TS_EXECUTED and the response carries the custom header.

middleware.ts alone (identical logic, old filename and export name) — it also still runs, but every dev/build logs a deprecation warning first:

⚠ The "middleware" file convention is deprecated. Please use "proxy" instead.

  To migrate automatically, run:
  npx @next/codemod@canary middleware-to-proxy .

  Learn more: https://nextjs.org/docs/messages/middleware-to-proxy

MIDDLEWARE_TS_EXECUTED /
 GET / 200 in 2.2s (next.js: 1872ms, proxy.ts: 48ms, application-code: 281ms)

Notice that last line: the internal timing breakdown labels the phase proxy.ts: 48ms even though the file on disk is still named middleware.ts. The rename runs deep enough into the runtime's own instrumentation that the old filename's execution gets reported under the new name.

Both files present at once — this is the case that actually matters for a migration, and Next.js does not pick a winner quietly:

⚠ The "middleware" file convention is deprecated. Please use "proxy" instead.
  ...
Unhandled Rejection: Error: Both middleware file "./middleware.ts" and proxy file "./proxy.ts" are detected. Please use "./proxy.ts" only. Learn more: https://nextjs.org/docs/messages/middleware-to-proxy

A hard build error, not an ambiguity the framework resolves for you — which matters if you're migrating an existing codebase incrementally and might, even briefly, leave both files in a branch.

A few more specifics worth having on hand for an interview: there's an official codemod (npx @next/codemod@canary middleware-to-proxy .) that renames the file and the export automatically. The exported function may be a named proxy export (as above) or a default export — both work, mirroring the old middleware/default-export flexibility. And as of 16.0.0, Proxy defaults to the Node.js runtime, not the Edge runtime that middleware.ts defaulted to for years — a real behavioural change, not just a naming one, since it means proxy.ts can now use Node.js-only APIs it couldn't before, at the cost of the cold-start characteristics of Edge.

Part 1 — React 19 concurrency internals

1.1 Why startTransition had to change

React 18 introduced startTransition, but it only accepted a synchronous callback. Passing an async function worked syntactically — JavaScript doesn't stop you — but React lost track of the transition the moment the wrapper function returned a pending Promise instead of undefined: the outer call looked "finished" to the scheduler while the real work was still in flight, so isPending flipped back to false immediately instead of staying true until the async work actually settled.

React 19 fixes this by teaching the transition machinery to track a returned Promise explicitly. Confirmed against the actual installed type definitions (@types/[email protected]), startTransition's parameter type is:

// VoidOrUndefinedOnly is an internal, non-exported helper type in React's own .d.ts —
// reproduced here so the signature below compiles standalone; its meaning is exactly
// what it says: `void` or `undefined`, nothing else.
type VoidOrUndefinedOnly = void | undefined;

type TransitionFunction = () => VoidOrUndefinedOnly | Promise<VoidOrUndefinedOnly>;
declare function startTransition(scope: TransitionFunction): void;

That Promise<VoidOrUndefinedOnly> branch is the whole fix, encoded directly in the type: pass an async arrow function, and React now keeps isPending true for the full duration of the returned promise, not just until the synchronous part of the function returns.

+-------------------------------------------------------+
| User Action (Click / Submit)                           |
+-------------------------------------------------------+
                           |
                           v
+-------------------------------------------------------+
| React 19 Fiber Scheduler: Transition Lane               |
| - Low-priority lane assigned                             |
| - isPending marked TRUE                                  |
| - Yields if a higher-priority task (typing, scroll) lands |
+-------------------------------------------------------+
                           |
                           v
+-------------------------------------------------------+
| Async Execution (Server Action / fetch)                 |
| - UI stays fully interactive throughout                  |
+-------------------------------------------------------+
                           |
                           v
+-------------------------------------------------------+
| Commit: Transition Resolves                              |
| - isPending set FALSE                                    |
| - Reconciled tree commits atomically — no partial flash   |
+-------------------------------------------------------+

Three mechanics fall out of this that an interviewer will probe individually:

1. Fiber lanes. Async actions get scheduled on a low-priority TransitionLane. Genuinely urgent input — typing, scrolling — lives on higher-priority lanes (SyncLane, InputContinuousLane) and interrupts an in-flight transition's reconciliation rather than queuing behind it.
2. Atomic commits. State updates that occur during the pending transition don't paint intermediate, half-finished states to the screen; React batches them and commits once, when the whole transition settles.
3. Suspense-aware. If the async transition trips a <Suspense> boundary further down the tree, React holds the current screen in place instead of tearing it down to the fallback — the visible UI doesn't regress to a spinner just because new data is loading behind it.

1.2 useActionState and useOptimistic in a real form

These two hooks are how a Client Component drives a Server Action without hand-rolling isPending state, error state, and optimistic rollback separately. All four hook signatures below (useActionState, useOptimistic, use, startTransition) are real, stable exports on the installed [email protected] package — confirmed with typeof React.useActionState === 'function' at runtime, not just present in the type definitions.

The domain types this section and Part 4 share:

// lib/types/products.ts
export interface Product {
  id: string;
  title: string;
  description: string;
  price: number;
}

export interface Review {
  id: string;
  productId: string;
  comment: string;
  rating: number;
  createdAt: string;
  isPending?: boolean;
}

export interface ReviewActionState {
  status: 'idle' | 'success' | 'error';
  errors: Record<string, string[]>;
}

// components/products/ProductReviewForm.tsx
'use client';

import { useActionState, useOptimistic, useRef, startTransition } from 'react';
import { submitReviewAction } from '@/lib/actions/product-actions';
import type { Review, ReviewActionState } from '@/lib/types/products';

interface ProductReviewFormProps {
  productId: string;
  initialReviews: readonly Review[];
}

const initialState: ReviewActionState = { status: 'idle', errors: {} };

export function ProductReviewForm({ productId, initialReviews }: ProductReviewFormProps) {
  const formRef = useRef<HTMLFormElement>(null);

  // useActionState owns the async lifecycle: pending flag, last result, dispatcher
  const [state, formAction, isPending] = useActionState(
    async (prevState: ReviewActionState, formData: FormData): Promise<ReviewActionState> => {
      const result = await submitReviewAction(prevState, formData);
      if (result.status === 'success') formRef.current?.reset();
      return result;
    },
    initialState
  );

  // useOptimistic renders a provisional value immediately, rolled back automatically on error
  const [optimisticReviews, setOptimisticReviews] = useOptimistic(
    initialReviews,
    (current: readonly Review[], newReview: Review) => [newReview, ...current]
  );

  const handleClientSubmit = (formData: FormData): void => {
    const comment = formData.get('comment')?.toString() ?? '';
    const rating = Number(formData.get('rating') ?? 5);

    const temporaryReview: Review = {
      id: `temp-${Date.now()}`,
      productId,
      comment,
      rating,
      createdAt: new Date().toISOString(),
      isPending: true,
    };

    // startTransition wraps the optimistic write + the real submission together
    startTransition(async () => {
      setOptimisticReviews(temporaryReview);
      await formAction(formData);
    });
  };

  return (
    <div className="space-y-6">
      <form ref={formRef} action={handleClientSubmit} className="space-y-4">
        <input type="hidden" name="productId" value={productId} />
        <div>
          <label htmlFor="rating" className="block text-sm font-medium">Rating</label>
          <select id="rating" name="rating" className="border rounded p-2 w-full" disabled={isPending}>
            <option value="5">5 Stars</option>
            <option value="4">4 Stars</option>
            <option value="3">3 Stars</option>
          </select>
        </div>
        <div>
          <label htmlFor="comment" className="block text-sm font-medium">Review</label>
          <textarea id="comment" name="comment" rows={3} className="border rounded p-2 w-full" disabled={isPending} />
          {state.errors.comment && (
            <p className="text-red-500 text-sm mt-1">{state.errors.comment.join(', ')}</p>
          )}
        </div>
        <button type="submit" disabled={isPending} className="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50">
          {isPending ? 'Submitting...' : 'Post Review'}
        </button>
      </form>

      <ul className="divide-y border rounded">
        {optimisticReviews.map((rev) => (
          <li key={rev.id} className={`p-4 ${rev.isPending ? 'opacity-40 bg-gray-50' : ''}`}>
            <span className="font-bold">{rev.rating} ★</span> — {rev.comment}
            {rev.isPending && <span className="ml-2 text-xs text-gray-500">(Sending...)</span>}
          </li>
        ))}
      </ul>
    </div>
  );
}

useOptimistic's real installed signature has two overloads — a shorthand where the update function receives the new value directly, and a reducer form for more complex merges:

declare function useOptimistic<State>(
  passthrough: State
): [State, (action: State | ((pendingState: State) => State)) => void];
declare function useOptimistic<State, Action>(
  passthrough: State,
  reducer: (state: State, action: Action) => Action
): [State, (action: Action) => void];

The rollback behaviour is automatic and worth stating precisely, because it's the part that's easy to get wrong in your head: if the action wrapped in the same startTransition throws or resolves to an error state, React discards the optimistic value and re-renders from the last committed state — you don't write any rollback code yourself, but you also don't get to intercept the rollback; the optimistic list entry simply disappears on the next render once the real state settles.

1.3 The React Compiler: why hand-written useMemo/useCallback can now hurt

The React Compiler is a build-time AST transform that infers a component's reactive dependencies and inserts memoization automatically, replacing manually-written useMemo/useCallback calls with generated ones keyed off a per-component memo-cache slot array.

Before the compiler:

function RawComponent({ items, filter }: { items: string[]; filter: string }) {
  const filtered = useMemo(() => items.filter((i) => i.includes(filter)), [items, filter]);
  const handleClick = useCallback(() => { console.log(filtered); }, [filtered]);
  return <Child items={filtered} onClick={handleClick} />;
}

What the compiler emits (a representative simplification of the real output — the actual generated code uses internal helper names, but the shape is accurate):

function CompiledComponent(props) {
  const $ = useMemoCache(4); // one fixed-size slot array per component instance
  const { items, filter } = props;

  let filtered;
  if ($[0] !== items || $[1] !== filter) {
    filtered = items.filter((i) => i.includes(filter));
    $[0] = items;
    $[1] = filter;
    $[2] = filtered;
  } else {
    filtered = $[2];
  }

  let handleClick;
  if ($[2] !== filtered) {
    handleClick = () => { console.log(filtered); };
    $[3] = handleClick;
  } else {
    handleClick = $[3];
  }

  return <Child items={filtered} onClick={handleClick} />;
}

The uncomfortable part, since the compiler is genuinely good at this: hand-written memoization now competes with the compiler's own analysis, and it usually loses.

1. Dependency-array overhead is real, per render. useMemo's dependency array is itself a new array literal allocated on every render, then compared element-by-element with Object.is. For a component that re-renders often with a cheap computation, the bookkeeping can cost more than just recomputing.
2. Closures pin memory. A useCallback-retained function closes over its entire lexical scope. If that scope includes a large object the component no longer visibly uses, the closure keeps it reachable and un-garbage-collectible for as long as the memoized function reference survives.
3. Unstable dependencies silently defeat the memo while still paying its cost. An inline object or array literal passed as a dependency (useMemo(fn, [{ id }])) is a new reference every render, so the cache misses on every single call — you get zero caching benefit while still paying the array-allocation and comparison overhead on every render.

The compiler avoids all three by generating dependency comparisons from a static analysis of the function body itself, keyed to a fixed-size slot array rather than a freshly-allocated array literal, and by scoping each generated memo to exactly the values the compiler can prove are read — no incidental closures over unrelated scope. The practical guidance for a codebase adopting the compiler: stop writing useMemo/useCallback for the common cases (derived values, event handlers passed to memoized children) and let the compiler generate them; keep them only where you need a semantic guarantee the compiler doesn't provide, like intentionally caching an expensive imperative call across unrelated renders via a stable ref.

1.4 Suspense streaming, at the wire level

Wrapping a slow subtree in <Suspense fallback={<Skeleton />}> doesn't just show a spinner — it changes what the server actually sends, in what order:

1. The server emits the initial HTML immediately, with the fallback's markup in place of the still-pending subtree.
2. It keeps the HTTP response open and continues rendering the suspended subtree in the background, without blocking anything else in the response.
3. When the subtree resolves, the server writes an additional out-of-band HTML chunk plus a small inline script that swaps it into place:

<div id="$RC_1">...resolved component html...</div>
<script>
  $RC('$RC_1', '$fallback_1'); // swap the fallback DOM node for the resolved one
</script>

1. The browser hydrates the resolved chunk as soon as it arrives, independently of whatever else on the page is still pending — a slow chart component doesn't hold up hydration of a fast sidebar rendered in a sibling boundary.

The practical consequence, and a genuinely good interview answer to "how would you speed up a page with one slow data source": put the slow thing behind its own <Suspense> boundary rather than await-ing it at the top of the page component. The rest of the page ships and becomes interactive immediately; only the boundary's own fallback waits.

Senior interview defense — React 19 concurrency

Q: How does useTransition prevent tearing during concurrent rendering?

Tearing is when the UI shows two different snapshots of state within the same paint — part of the screen reflecting old data, part reflecting new. For state that lives outside React (a global variable, a browser API), useSyncExternalStore exists specifically to force a synchronous, tear-free read. For state that lives inside React, a transition builds a new work-in-progress fiber tree on a low-priority lane and does not commit any of it to the DOM until the whole tree finishes rendering. If a higher-priority update arrives mid-transition — a keystroke, for instance — React aborts or yields the in-progress work, commits the high-priority update against the current (already-committed) tree immediately, then restarts the transition from that new baseline. The DOM only ever reflects one complete, internally consistent state at a time.

Q: What happens to an error thrown inside startTransition(async () => {...}) versus one thrown inside a Server Action bound to useActionState?

A raw startTransition(async () => { throw ... }) produces an unhandled promise rejection that bubbles to the nearest error boundary (error.tsx) if one exists, or terminates uncaught in the runtime if not — you get no structured error state, just a boundary fallback or a crash. useActionState, by contrast, wraps the action call in its own reconciliation guard: the action is expected to return a typed result object rather than throw, so a well-written action catches its own errors and resolves to { status: 'error', ... }, which useActionState hands back as state without unmounting anything. If the action genuinely throws an unhandled exception anyway, useActionState still catches it at the hook boundary, rolls back any useOptimistic values that were staged inside the same transition, and only then defers to the nearest error.tsx.

Part 2 — The RSC wire format and the Server/Client boundary

2.1 What actually goes over the wire on a soft navigation

Click a <Link> to a new route and the browser does not fetch HTML. It fetches the React Server Components payload — colloquially the "Flight" stream — a compact, line-delimited, partially-JSON format describing a tree of React elements, not a rendered document.

GET /products/101 HTTP/1.1
RSC: 1
Next-Router-State-Tree: [...]

The response is a sequence of numbered rows streamed as they become ready — this is a representative shape of the format, not a byte-for-byte spec (the exact framing is a Next.js/React implementation detail that has changed before and can change again; the concept — three cooperating kinds of row — is the durable part):

1:I{"id":"1048","chunks":["client-chunk-1048.js"],"name":"ProductReviewForm","async":false}
2:{"id":"p-101","title":"Ergonomic Mechanical Keyboard","price":189.99}
0:["$","div",null,{"className":"container","children":[["$","h1",null,{"children":"Ergonomic Mechanical Keyboard"}],["$","$L1",null,{"productId":"p-101","initialReviews":[]}]]}]

Three cooperating row types:

• 1:I{...} — an import row. It registers a Client Component reference (ProductReviewForm) and names the JS chunk the browser needs to actually execute it (client-chunk-1048.js).
• 2:{...} — a data row. Plain serialized JSON — the props and models the tree needs.
• 0:[...] — the element row. A React element tree encoded as nested arrays: the literal "$" marks a React element (roughly React.createElement's shape), and "$L1" is a placeholder telling the client "mount the Client Component registered at row 1 here, with these props," rather than embedding that component's own rendered output inline.

+-------------------------------------------------------+
| Import row: registers a Client Component reference       |
| 1:I{"id":"1048","name":"ProductReviewForm"}              |
+-------------------------------------------------------+
                           |
                           v
+-------------------------------------------------------+
| Data row: serialized JSON models                          |
| 2:{"id":"p-101", "price": 189.99}                         |
+-------------------------------------------------------+
                           |
                           v
+-------------------------------------------------------+
| Element row: tag, key, props, children                    |
| 0:["$","div",null,{"children":[..., ["$","$L1",...]]}]    |
+-------------------------------------------------------+

2.2 The serialization boundary — what can and can't cross it

Every "use client" file compiles into its own module graph, separate from the Server Component graph, and the two only communicate through this serialized wire format. That has hard, mechanical consequences for what you're allowed to pass as a prop from a Server Component into a Client Component.

Crosses cleanly:

1. Primitives — string, number, boolean, null, undefined, bigint.
2. Plain data structures — object literals, arrays, Map, Set.
3. Binary — Uint8Array, ArrayBuffer.
4. Unresolved Promises — a Server Component can pass a still-pending Promise as a prop; the Client Component unwraps it with React 19's use() hook inside a <Suspense> boundary (the mechanism behind Part 5's shared-session pattern).
5. React elements themselves, when passed as children.

Cannot cross:

1. Functions — not JSON-serializable, with the one deliberate exception of a "use server" Server Action, which crosses as an opaque callable reference ID rather than actual function bytes.
2. Class instances — lose their prototype chain entirely; a new Date() becomes a plain serialized value on the other side, and any custom methods on a class instance are simply gone.
3. DOM nodes / window / document — don't exist on the server in the first place.
4. Unregistered Symbols — can't be reconstructed identically across the process boundary.

2.3 A Client Component still runs on the server — just not always

"use client" marks the boundary of interactivity, not "runs only in the browser." What actually happens depends on how the page was reached:

Direct URL hit / hard reload
=============================
1. Server Components execute -> produce the RSC payload.
2. Client Components ALSO execute on the server -> produce their static HTML markup.
3. Response = combined HTML (server shell + server-rendered client markup), sent to the browser.
4. Browser paints the complete HTML immediately (fast FCP/LCP).
5. Hydration: React downloads the client JS chunks, re-runs Client Component logic client-side,
   reconciles against the existing SSR'd DOM, and attaches event listeners — without re-painting.

Soft navigation (clicking a <Link>)
====================================
1. Client Components do NOT execute on the server for this request.
2. The server runs only the requested Server Components and returns an RSC Flight payload.
3. The client reconciles that payload directly into its already-hydrated Virtual DOM.

The direct consequence: a "use client" file still needs to be safe to execute in a restricted, Node-shimmed environment during SSR — it just can't reach true Node built-ins (fs, net) even though it's technically executing inside the Node process, because the bundler compiles it against a client-shaped module graph that doesn't resolve those imports at all.

Senior interview defense — RSC boundary and serialization

Q: If a Client Component executes on the server during SSR, why can't it read fs or hold a live database connection pool?

Next.js maintains two separate compilation graphs — a Server Components graph and a Client Components graph — determined by the "use client" directive at build time, not by which process happens to execute the code at runtime. A file compiled into the client graph has its imports resolved against a bundle that doesn't include Node.js built-ins at all; importing fs or a database driver from a "use client" file fails at build time with a module-resolution error, before the app ever runs. During SSR, the server does execute Client Component code, but it runs the already-compiled client bundle in a sandboxed environment that mirrors the browser's module graph — it isn't given access to the unrestricted server-side Node context just because it happens to be running inside the same process.

Q: How does passing a Promise from a Server Component into a Client Component differ from fetching inside useEffect?

useEffect-based fetching is a strict waterfall: server renders and sends HTML → browser downloads it → browser downloads and parses the JS bundle → browser executes it → the effect fires → a network request goes out → the response comes back → the UI finally updates. Every arrow there is sequential, and several of them are entirely client-side round trips that could have started on the server instead.

Passing an unresolved Promise from a Server Component starts the actual data fetch immediately, during the initial server render — the RSC payload streams an open chunk reference for that still-pending value rather than waiting for it. The Client Component consumes it with use(promise) inside a <Suspense> boundary, and the data arrives over the same connection that delivered the rest of the page — there is no second client-initiated HTTP round trip, and the fetch started earlier (at the beginning of the server render) than an effect ever could have.

Part 3 — Cache Components: the caching model, correctly, for 16.3.6

This is the part of the framework where stale material does the most damage, because the model genuinely changed shape — not just the config flag name, but the mental model of what "caching" means in an App Router project. Everything below is read directly from the shipped documentation and type definitions in node_modules/next/, and rebuilt against real next build runs.

3.1 The shift: from implicit, global caching to explicit, local caching

Pre-16 Next.js cached fetch() calls by default (cache: 'force-cache') inside an opaque, route-wide Data Cache, and a whole route was either static or dynamic as a unit. 16 inverts both defaults:

Enabling it is one flag, the same cacheComponents: true from Part 0.5. Nothing in Part 3 works without it — every directive below fails the build outright if the flag is off, which is itself worth internalising: this isn't a soft degrade to "always fresh," it's a hard build error naming exactly what you forgot.

3.2 Three cache directives, not one

Under Cache Components there are three distinct 'use cache' variants, and the difference between them is precisely which runtime APIs each one is allowed to read and where its result is allowed to live:

• 'use cache' — the plain form. Cannot read cookies(), headers(), or searchParams at all; every argument and closed-over value becomes part of the cache key. Result lives server-side (in-memory by default, or durably with the remote variant below), shared across every user who hits the same cache key.
• 'use cache: private' — reads cookies(), headers(), and searchParams directly (not connection()). Its result is kept in the browser only — never on the server — so per-user data never risks leaking into a shared server-side cache entry. It cannot read connection().
• 'use cache: remote' — a plain 'use cache' whose result is written to a durable, shared cache handler instead of transient per-instance memory, so it survives across serverless instances and cold starts. Costs a network round trip on write, so it only pays off at a high hit rate.

A concrete rule that trips people up in exactly the way an interview question wants it to: cookies() inside a plain 'use cache' function is a build error, and it doesn't just fail that one route — it kills the entire production build. Real, verbatim transcript from a minimal repro:

import { cookies } from 'next/headers';

async function getGreeting() {
  'use cache';
  const cookieStore = await cookies(); // ILLEGAL inside plain 'use cache'
  const name = cookieStore.get('name')?.value ?? 'stranger';
  return `Hello, ${name}`;
}

⨯ Error: Route /test-auth-misuse used `cookies()` inside "use cache". Accessing Dynamic data
sources inside a cache scope is not supported. If you need this data inside a cached function
use `cookies()` outside of the cached function and pass the required dynamic data in as an
argument. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache
    at g (app/test-auth-misuse/page.tsx:9:29)
   7 | async function getGreeting() {
   8 |   "use cache";
>  9 |   const cookieStore = await cookies();
     |                             ^
  10 |   const name = cookieStore.get("name")?.value ?? "stranger";
  ...
Export encountered an error on /test-auth-misuse/page: /test-auth-misuse, exiting the build.
⨯ Next.js build worker exited with code: 1 and signal: null

Export encountered an error ... exiting the build — a single misplaced cookies() call takes down the entire production build, not just the route it's in. The reasoning is straightforward once stated: a plain 'use cache' boundary is shared across every request that hits the same cache key, and cookies()/headers() are per-request by definition — allowing them in would mean either poisoning one user's session data into another user's cached response, or silently ignoring the read, neither of which the framework is willing to do quietly. The fix, per the error's own guidance: read cookies() outside the cached function and pass only the specific value you need in as an argument — or switch to 'use cache: private' (Part 5.2), which is built for exactly this case.

3.3 Data-level and UI-level caching

'use cache' can wrap either a plain async function (data-level) or an async component (UI-level, caching the rendered RSC output itself):

// lib/api/products.ts
import 'server-only';
import { cacheLife, cacheTag } from 'next/cache';
import type { Product } from '@/lib/types/products';

export async function getProductCatalog(category: string): Promise<Product[]> {
  'use cache';
  cacheLife('hours');
  cacheTag('products', `category-${category}`);

  const res = await fetch(`https://api.internal.enterprise/products?cat=${encodeURIComponent(category)}`, {
    headers: { Authorization: `Bearer ${process.env.INTERNAL_API_SECRET}` },
  });

  if (!res.ok) throw new Error(`Failed to fetch catalog: ${res.statusText}`);
  return (await res.json()) as Product[];
}

// components/products/CachedProductDetails.tsx
import { cacheLife, cacheTag } from 'next/cache';
import type { Product } from '@/lib/types/products';

export async function CachedProductDetails({ productId }: { productId: string }) {
  'use cache';
  cacheLife('days');
  cacheTag('product-details', `product-${productId}`);

  const product = await fetchProductById(productId);
  return (
    <div className="border p-6 rounded-lg shadow-sm">
      <h2 className="text-2xl font-bold">{product.title}</h2>
      <p className="text-gray-600 mt-2">{product.description}</p>
      <span className="text-xl font-semibold mt-4 block">${product.price.toFixed(2)}</span>
    </div>
  );
}

async function fetchProductById(id: string): Promise<Product> {
  const res = await fetch(`https://api.internal.enterprise/products/${id}`);
  return res.json();
}

cacheTag's real signature takes a rest parameter of strings, not an array: cacheTag(...tags: string[]): void. cacheLife accepts either a named profile, a custom profile name declared in next.config.ts, or an inline object:

declare function cacheLife(profile: 'default' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'max'): void;
declare function cacheLife(profile: string): void;
declare function cacheLife(profile: { stale?: number; revalidate?: number; expire?: number }): void;

3.4 The three intervals a cacheLife profile actually controls

Timeline:
|---------- stale (300s) ----------|----- revalidate (900s) -----|----- expire (3600s) -----|
^                                  ^                             ^                          ^
Client serves from local cache     Background regeneration        Entry expires; the NEXT
without contacting the server      triggers on the next hit       request blocks until fresh

• stale — how long the client router cache may serve a value with zero server contact.
• revalidate — the server-side stale-while-revalidate window: an incoming hit past this point still gets the cached value immediately, but triggers a background regeneration for the next request.
• expire — the hard ceiling. Past this, the entry is dropped, and the next request blocks synchronously until a fresh value is generated.

3.5 Invalidation: revalidateTag grew a mandatory second argument

This is the single most consequential breaking change in this whole guide for anyone porting existing code, and it fails loudly rather than silently: in 16.3.6, revalidateTag requires two arguments.

export declare function revalidateTag(tag: string, profile: string | { expire?: number }): undefined;

The old, pre-16 single-argument call is now a compile error, not a warning:

$ npx tsc --noEmit
app/api/revalidate/route.ts(6,3): error TS2554: Expected 2 arguments, but got 1.

// app/api/revalidate/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { revalidateTag } from 'next/cache';

interface RevalidateRequestBody {
  tag: string;
  secret: string;
}

export async function POST(request: NextRequest): Promise<NextResponse> {
  const body = (await request.json()) as Partial<RevalidateRequestBody>;

  if (body.secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ message: 'Invalid revalidation token' }, { status: 401 });
  }
  if (!body.tag || typeof body.tag !== 'string') {
    return NextResponse.json({ message: 'Missing tag parameter' }, { status: 400 });
  }

  // The second argument names the cacheLife profile to apply to the invalidated entry
  // going forward, or supplies an inline { expire } override.
  revalidateTag(body.tag, 'max');

  return NextResponse.json({ revalidated: true, tag: body.tag, timestamp: Date.now() });
}

For the specific case of "the current request's own author needs to see their own write immediately" — the classic read-your-own-writes problem inside a Server Action — next/cache now exports a distinct, single-argument function for exactly that: updateTag(tag: string): undefined. It's the closer analog to the old one-argument revalidateTag behaviour, deliberately scoped to be callable only from a Server Action rather than from an arbitrary Route Handler.

3.6 Random values, timestamps, and connection()

Math.random(), Date.now(), and crypto.randomUUID() are non-deterministic by definition, which means Cache Components has to force an explicit choice about them rather than silently baking one possible value into the static shell forever. Call connection() first to defer the value to real request time (and wrap in <Suspense>, since deferring makes it a runtime read like any other):

import { connection } from 'next/server';
import { Suspense } from 'react';

async function UniqueContent() {
  await connection();
  const uuid = crypto.randomUUID();
  return <p>Request ID: {uuid}</p>;
}

export default function Page() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <UniqueContent />
    </Suspense>
  );
}

Or, deliberately go the other way and cache a single generated value for everyone until the next revalidation:

export default async function Page() {
  'use cache';
  const buildId = crypto.randomUUID();
  return <p>Build ID: {buildId}</p>;
}

performance.now() is exempt from this guard — it's understood to be for telemetry, not for rendering content, so Next.js doesn't treat it as something that needs connection().

3.7 Partial Prerendering, end to end

With cacheComponents: true (and therefore PPR on by default — there's no longer a separate PPR flag to flip), a route's static and dynamic parts are compiled into a single static shell at build time, with live holes left open exactly where they're needed:

// app/products/[id]/page.tsx
import { Suspense } from 'react';
import { CachedProductDetails } from '@/components/products/CachedProductDetails';
import { DynamicInventoryStatus } from '@/components/products/DynamicInventoryStatus';

export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;

  return (
    <main className="container mx-auto p-6 space-y-6">
      {/* STATIC: prerendered at build time, part of the shell */}
      <header className="border-b pb-4">
        <h1 className="text-3xl font-extrabold tracking-tight">Enterprise Store</h1>
      </header>

      {/* CACHED: output cached via 'use cache', still joins the static shell */}
      <CachedProductDetails productId={id} />

      {/* DYNAMIC HOLE: streamed at request time, over the same connection */}
      <Suspense fallback={<div className="h-12 bg-gray-100 animate-pulse rounded" />}>
        <DynamicInventoryStatus productId={id} />
      </Suspense>
    </main>
  );
}

// components/products/DynamicInventoryStatus.tsx
import { headers } from 'next/headers';

export async function DynamicInventoryStatus({ productId }: { productId: string }) {
  const headerList = await headers(); // runtime read — must sit behind Suspense
  const userAgent = headerList.get('user-agent') ?? 'unknown';

  const res = await fetch(`https://api.internal.enterprise/inventory/${productId}`, { cache: 'no-store' });
  const data = await res.json();

  return (
    <div className="bg-amber-50 p-4 rounded border border-amber-200">
      <p className="text-amber-900 font-medium">
        Inventory Level: <strong>{data.availableUnits} units</strong> available.
      </p>
      <span className="text-xs text-amber-700">Client Platform: {userAgent}</span>
    </div>
  );
}

The general shape of the rule, stated once so it doesn't need to be memorised per API: a component becomes part of the static shell if everything it does is either predictable (pure computation, static imports, fs.readFileSync on a build-time-stable file) or explicitly cached ('use cache'); it becomes a streamed, request-time hole the moment it touches a genuinely runtime source (cookies(), headers(), un-cached fetch, connection()) — and the framework requires that hole to be wrapped in <Suspense>, refusing to build otherwise. A real build with this exact shape produces a route table annotated with the cache profile actually applied:

▲ Next.js 16.3.6 (Turbopack)
- Cache Components enabled
- Partial Prefetching enabled

Route (app)           Revalidate  Expire
┌ ○ /
├ ○ /_not-found
└ ○ /products/[id]            1m      1h

Push dynamic reads as far down the tree as possible. A params/cookies()/headers() read at the top of a layout holds the entire segment — including {children} — behind that one runtime read. Moving the same await into a small leaf component, itself wrapped in its own <Suspense>, lets everything else in the layout (the sidebar, the shared chrome) stay in the static shell:

// Before: the whole layout — sidebar included — becomes a dynamic hole
export default async function Layout({ children, params }: LayoutProps<'/shop/[slug]'>) {
  const { slug } = await params;
  return (<div><Sidebar /><h1>{slug}</h1>{children}</div>);
}

// After: only the heading streams; Sidebar and children stay in the static shell
export default function Layout({ children, params }: LayoutProps<'/shop/[slug]'>) {
  return (
    <div>
      <Sidebar />
      <Suspense fallback={<h1>Loading...</h1>}>
        {params.then(({ slug }) => <SlugHeading slug={slug} />)}
      </Suspense>
      {children}
    </div>
  );
}

3.8 Prefetching, instant navigation, and bots

partialPrefetching (Part 0.5) governs how much of a route <Link> fetches ahead of a click. By default it prefetches the route's App Shell — its static content plus any session data already derivable from cookies()/headers(). Set prefetch={true} explicitly on a given <Link> to also prefetch content that depends on that link's own destination URL (searchParams, dynamic params) — this re-renders the destination's component tree at prefetch time with the real URL resolved, which costs one extra server invocation per prefetchable link, and is why it's opt-in rather than default.

Two more pieces of the model worth stating precisely because they resolve otherwise-confusing framework behaviour: crawlers don't get the shell-plus-streaming treatment at all. Next.js detects bots by user agent and, because a crawler needs one complete document rather than a progressively-streamed one, renders the entire page dynamically at request time and only responds once it's fully finished — which means anything that "completed during prerendering" for a human visitor has to be able to re-run correctly at request time for a bot, or the bot gets a broken page even though real users never see a problem.

And Cache Components validates client-side navigations, not just direct visits, for exactly this shell/hole structure — a <Suspense> boundary that correctly covers a hard page load can still be missing during a client-side transition if the component structure differs between the two, and the framework's dev-mode validation is specifically there to catch that gap before it ships.

Senior interview defense — caching and PPR

Q: What happens if you call cookies() or headers() inside a scope marked 'use cache'?

It's a hard build-time error, not a runtime fallback or a silent no-op — confirmed above with the actual compiler message. The reasoning: a plain 'use cache' result is shared across every request that resolves to the same cache key, so admitting a per-request value like a cookie into that scope would mean either leaking one user's session data into another user's cached response, or the framework silently discarding the dynamic read and serving stale/wrong personalization — Next.js refuses to make that call for you. The fix is one of two shapes: switch to 'use cache: private', which is allowed to read cookies()/headers() directly but keeps its result client-side only, per-user; or read the dynamic value outside the cache boundary and pass just the derived, safe-to-share piece (a userId, not the whole session) in as an argument, which becomes part of the cache key.

Q: How does Partial Prerendering avoid a race condition when a dynamic chunk resolves after the static shell has already hydrated?

The static shell ships with a uniquely-IDed placeholder node for every dynamic hole. The client hydrates everything in the static shell normally, on its own schedule, while the connection for the dynamic chunk stays open in the background. React's streaming parser attaches hydration listeners scoped to each boundary independently — it doesn't treat the page as one atomic hydration unit. When the dynamic RSC payload for a given hole finally arrives, React resolves that sub-fiber alone: it inserts the new markup and hydrates just that boundary, without touching, re-mounting, or tearing any subtree outside it that already finished hydrating. The isolation is per-boundary by construction, which is exactly what makes streaming safe under Suspense rather than a source of hydration races.

Part 4 — Server Actions: what's actually protected, and what isn't

4.1 A Server Action is a public POST endpoint, full stop

A "use server" function is not a private RPC call reachable only from your own UI. It compiles to a real HTTP endpoint with a stable-per-build, opaque ID, callable by anyone who can construct the right request — cURL, a script, a browser extension. Treat it exactly like you'd treat any other unauthenticated-by-default POST route, because that's what it is.

Next.js does provide real, built-in mitigations, and it's worth being precise about what they cover:

1. Same-origin verification. Confirmed current against the shipped docs: "To prevent CSRF attacks, Next.js compares the host in a request's Origin header against the app's own host, taken from x-forwarded-host or host, and rejects the action when the two differ." This has been the default since Server Actions went stable and is unchanged in 16. Two caveats worth stating precisely rather than glossing: the documentation says the mismatched request is "rejected," not literally that it returns HTTP 403 — in practice it surfaces as an "Invalid Server Actions request" error, commonly implemented as a 403, but that's the practical effect, not the exact contract. And a request with no Origin header at all is currently let through with only a warning, not rejected — a real gap in the default posture, not a hardened wall. There was also a genuine regression worth knowing by name: CVE-2026-27978, affecting Next.js 16.0.1–16.1.6, where an opaque origin: null (the value a sandboxed iframe sends) was mishandled as equivalent to "missing" and could bypass the check entirely — patched in a later 16.x release. If you're auditing a project, confirm the installed version is past that range.
2. Non-guessable, build-rotated action IDs. Actions don't map to predictable URLs; Next.js generates a cryptographic hash per action that changes on every build, so an ID discovered in one deployment's client bundle doesn't work against the next.
3. Dead-code elimination. A Server Action that's defined but never actually imported by any Client Component is stripped from the client bundle entirely — it never becomes a callable RPC target in the first place.

None of these three amount to authentication or authorization. They stop a specific class of cross-site request forgery and reduce the action's discoverability; they say nothing about whether the caller is allowed to perform the action at all.

4.2 Authentication belongs inside the action, not just at the perimeter

A redirect issued from proxy.ts (or the old middleware.ts) feels like a security boundary, but it isn't one for Server Actions specifically: a Server Action is invoked directly by client-side JavaScript hitting its dedicated endpoint, and depending on your routing setup, rewrites, edge configuration, or a simple copy-pasted cURL command can reach it without ever passing back through the proxy's own request-handling path the way a page navigation does. Authentication and authorization have to be re-checked inside the action's own function body, every time, treating the proxy layer as a UX optimization (skip the flash of an unauthenticated page) rather than the actual security boundary.

// lib/security/session.ts
import 'server-only';
import { cookies } from 'next/headers';

export interface UserSession {
  userId: string;
  role: 'admin' | 'editor' | 'user';
}

export async function requireAuth(requiredRole?: 'admin' | 'editor'): Promise<UserSession> {
  const cookieStore = await cookies();
  const token = cookieStore.get('auth_session')?.value;

  if (!token) throw new Error('UNAUTHORIZED: No active session');

  const session = await verifyJwtToken(token);
  if (!session) throw new Error('UNAUTHORIZED: Invalid or expired session');

  if (requiredRole && session.role !== requiredRole && session.role !== 'admin') {
    throw new Error('FORBIDDEN: Insufficient administrative privileges');
  }

  return session;
}

async function verifyJwtToken(token: string): Promise<UserSession | null> {
  // Real implementation verifies a signature and expiry against a JWT/session store.
  if (token === 'valid_admin_token') return { userId: 'usr-902', role: 'admin' };
  return null;
}

4.3 Keeping raw server-side models out of the client payload

The concern this section addresses is real and common: a Server Action or an RSC prop that innocently returns { ...user } — spreading a full database row — ships whatever that row contains, including fields no one meant to expose, straight into the client bundle's flight payload. The disciplined fix that works on every React/Next.js version, and the one to lead with in an interview answer, is simply never returning the raw row: define a narrow, explicit shape ({ id, email }, not { ...user }) at the boundary, so there's nothing sensitive to accidentally leak.

React does also ship a pair of opt-in, fail-loud tainting APIs for the same purpose — experimental_taintUniqueValue and experimental_taintObjectReference — which mark a specific value or object reference so that passing it across the serialization boundary throws instead of silently serializing. Be precise about their availability before reaching for them: they exist only as ambient type declarations for React's experimental/canary channel (@types/react/experimental.d.ts), not in the standard index.d.ts a normal import ... from 'react' resolves against — and checked directly on the actual installed [email protected] runtime, both are undefined:

$ node -e "const React = require('react'); console.log(typeof React.experimental_taintUniqueValue, typeof React.experimental_taintObjectReference)"
undefined undefined

They are not "still experimental but usable" — they are simply not present in the package create-next-app installs today. Don't cite them as an available defense in a stable Next.js 16 project; the load-bearing mitigation is the narrow-return-shape discipline above, not a tainting API you can't currently import.

4.4 A production-shaped, schema-validated action

// lib/actions/product-actions.ts
'use server';

import { z } from 'zod';
import { revalidateTag } from 'next/cache';
import { requireAuth } from '@/lib/security/session';
import type { ReviewActionState } from '@/lib/types/products';

const ReviewSchema = z.object({
  productId: z.string().min(1, 'Product ID is required'),
  rating: z.coerce.number().min(1).max(5),
  comment: z.string().trim().min(5, 'Review must be at least 5 characters long').max(1000),
});

export async function submitReviewAction(
  prevState: ReviewActionState,
  formData: FormData
): Promise<ReviewActionState> {
  try {
    // 1. Authorization, evaluated inside the action every time — not just at the proxy
    const session = await requireAuth();

    // 2. Strict input parsing
    const parsed = ReviewSchema.safeParse({
      productId: formData.get('productId'),
      rating: formData.get('rating'),
      comment: formData.get('comment'),
    });

    if (!parsed.success) {
      // Zod 4: the deprecated `.flatten()` method still runs, but z.flattenError is current
      return { status: 'error', errors: z.flattenError(parsed.error).fieldErrors };
    }

    // 3. Execute
    await dbInsertReview({ ...parsed.data, userId: session.userId, createdAt: new Date().toISOString() });

    // 4. Targeted invalidation — note the now-mandatory second argument
    revalidateTag(`product-${parsed.data.productId}`, 'max');

    return { status: 'success', errors: {} };
  } catch (err: unknown) {
    const message = err instanceof Error ? err.message : 'Internal Server Error';
    return { status: 'error', errors: { form: [message] } };
  }
}

async function dbInsertReview(data: Record<string, unknown>): Promise<void> {
  // Persistence logic.
}

Senior interview defense — Server Action exploits

Q: An attacker inspects network traffic, extracts a Server Action's endpoint ID, and scripts a replay against it directly. What actually stops them?

Nothing about the ID being "hidden" — it's distributed to every authorized client's JS bundle, so treating it as a secret is a mistake. What actually stops the attack is whatever the action does with the caller's credentials and the request's shape: authenticating inside the action body on every invocation (requireAuth(), not a perimeter check), server-side idempotency keys to reject a duplicated submission, and rate limiting keyed to the authenticated user ID or client IP (a Redis token bucket, for instance). The action ID's build-rotation and non-guessability raise the cost of discovering the endpoint; they do nothing to stop a call once discovered, and the CSRF Origin check only stops a cross-site forgery — a same-origin scripted replay by an authenticated, malicious client sails straight through it.

Part 5 — Authentication: public routes, private routes, and sessions under Cache Components

5.1 Different layouts for public and private sections, via route groups

A route group — a folder wrapped in parentheses, (name) — organizes routes without adding a segment to the URL. Its most common real use is exactly this guide's requirement: giving a marketing/public section and an authenticated/private section two entirely different root layouts, without either segment appearing in the path.

app/
├── (marketing)/
│   ├── layout.tsx        # public chrome: marketing nav, footer, no auth check
│   ├── page.tsx          # "/"
│   └── pricing/
│       └── page.tsx      # "/pricing"
├── (dashboard)/
│   ├── layout.tsx        # app chrome: sidebar, user menu, session-aware
│   ├── overview/
│   │   └── page.tsx      # "/overview"
│   └── settings/
│       └── page.tsx      # "/settings"
└── layout.tsx             # true root layout — <html>/<body>, shared by both

(marketing) and (dashboard) never appear in the URL — app/(dashboard)/overview/page.tsx serves /overview, not /dashboard/overview. Three caveats from the shipped docs are worth internalising because each one is a real, reproducible failure mode, not a hypothetical:

1. A hard reload, not a soft transition, when the root layout changes. Navigating from a route under one group's root layout to a route under a different group's root layout forces a full page reload — this only applies when the groups define genuinely separate root layouts (each with its own <html>/<body>), not to nested layouts within a shared root.
2. Colliding paths are a build error. (marketing)/about/page.tsx and (dashboard)/about/page.tsx both resolve to /about and Next.js refuses to build rather than pick a winner.
3. Exactly one group needs to own /. With multiple root layouts and no single top-level layout.tsx, the home route must live inside one of the groups (e.g. app/(marketing)/page.tsx) — there's no implicit fallback.

5.2 Reading the session correctly under Cache Components

This is where the caching model from Part 3 and authentication genuinely intersect, and it's a pattern that didn't exist in this exact shape before Cache Components: a session read happens at request time by definition — it can't be part of the static shell — so authenticated UI has to stream in behind a <Suspense> boundary, and it's 'use cache: private', not a plain 'use cache', that's allowed to read the session cookie directly.

// lib/session.ts
import 'server-only';
import { cookies } from 'next/headers';
import { sealData, unsealData } from 'iron-session';

export type SessionData = { userId?: string };

const COOKIE_NAME = 'app_session';
const password = process.env.SESSION_PASSWORD!;

export async function getSession(): Promise<SessionData> {
  const cookie = (await cookies()).get(COOKIE_NAME)?.value;
  if (!cookie) return {};
  return unsealData<SessionData>(cookie, { password });
}

// lib/auth.ts
import 'server-only';
import { redirect } from 'next/navigation';
import { getSession } from './session';
import { findUserById } from './data';

export type User = { id: string; name: string };

export async function getCurrentUser(): Promise<User> {
  'use cache: private';

  const { userId } = await getSession();
  if (!userId) redirect('/login');

  const user = await findUserById(userId);
  if (!user) redirect('/login');

  return { id: user.id, name: user.name };
}

redirect() throws to interrupt rendering rather than returning a value, so a redirect is never itself what gets cached — only a fully resolved, legitimate user is. 'use cache: private' accepts cookies(), headers(), and searchParams, but explicitly not connection() — the private cache is for request-scoped-but-repeatable reads, not for forcing genuinely unique-per-call values.

The component that actually reads the session must sit behind <Suspense> — with Cache Components enabled, reading cookies() outside a boundary is a build error, the same class of error shown for plain 'use cache' in Part 3.6:

// app/(dashboard)/overview/page.tsx
import { Suspense } from 'react';
import { getCurrentUser } from '@/lib/auth';
import { getAnnouncements } from '@/lib/data';

export default function Page() {
  return (
    <main>
      {/* Cached, no session dependency — joins the static shell */}
      <Announcements />

      {/* Reads the session — streams in behind the boundary on every navigation */}
      <Suspense fallback={<p>Loading your dashboard…</p>}>
        <Dashboard />
      </Suspense>
    </main>
  );
}

async function Announcements() {
  'use cache';
  const announcements = await getAnnouncements();
  return (
    <ul>{announcements.map((a) => <li key={a}>{a}</li>)}</ul>
  );
}

async function Dashboard() {
  const user = await getCurrentUser();
  return <h1>Welcome, {user.name}</h1>;
}

Keep the session read out of a layout's top level specifically — an await getCurrentUser() at the top of app/(dashboard)/layout.tsx would hold the entire segment, {children} included, behind that one request-scoped read. Push it down into a leaf component inside its own boundary instead, exactly as in Part 3.7's "push dynamic reads down" rule — this is the same principle, and authentication is its most common real trigger.

5.3 Sharing the resolved user without prop-drilling or re-reading the session

You don't need to call getCurrentUser() again in every component that needs it. Read it once inside the boundary, then hand the still-unresolved Promise<User> down through React context and unwrap it with use() wherever it's needed — including from Client Components, which can consume a promise created on the server this way without an extra client-side fetch:

// app/user-provider.tsx
'use client';

import { createContext, use } from 'react';
import type { ReactNode } from 'react';
import type { User } from '@/lib/auth';

const UserContext = createContext<Promise<User> | null>(null);

export function UserProvider({ userPromise, children }: { userPromise: Promise<User>; children: ReactNode }) {
  return <UserContext value={userPromise}>{children}</UserContext>;
}

export function useUser() {
  const userPromise = use(UserContext);
  if (!userPromise) throw new Error('useUser must be used within a UserProvider');
  return use(userPromise);
}

function Dashboard() {
  const userPromise = getCurrentUser(); // NOT awaited here — handed down unresolved

  return (
    <UserProvider userPromise={userPromise}>
      <Suspense fallback={<span>Loading…</span>}>
        <UserBadge />
      </Suspense>
    </UserProvider>
  );
}

// app/user-badge.tsx
'use client';
import { useUser } from './user-provider';

export function UserBadge() {
  const user = useUser(); // suspends until the promise resolves
  return <span>Signed in as {user.name}</span>;
}

Because use() suspends the calling component until its promise settles, <UserBadge> needs its own <Suspense> ancestor — but critically, the promise itself was only created once, inside Dashboard's boundary, so every consumer resolves the same underlying session read rather than triggering a new one each.

5.4 Caching data that's derived from — but doesn't require re-reading — the session

Once you have a resolved user, cache the data you fetch for them by extracting just the userId and passing it into a plain 'use cache' function, which keeps the derived result on the server (unlike 'use cache: private', which never leaves the browser) and lets cacheTag invalidate it precisely:

// lib/data.ts
import 'server-only';
import { cacheLife, cacheTag } from 'next/cache';
import { getCurrentUser } from './auth';

export async function getNotes() {
  const user = await getCurrentUser();
  return getNotesByUserId(user.id); // only the id crosses into the cache scope
}

async function getNotesByUserId(userId: string) {
  'use cache';
  cacheTag(`notes:${userId}`);
  cacheLife('minutes');

  return db.query.notes.findMany({ where: (notes, { eq }) => eq(notes.userId, userId) });
}

Keep getNotesByUserId unexported. That's not a style nicety — it's what makes this safe: the only way to reach it is through getNotes(), which always resolves the id from the current, authenticated session rather than accepting one as an untrusted argument. If getNotesByUserId were exported and callable with an arbitrary userId, any caller could request any other user's notes by passing a different id — the classic insecure-direct-object-reference bug, except here it's structurally impossible rather than something you have to remember to check for on every call site. This unexported-inner-function shape, with all reads funneled through one authenticated entry point, is the Data Access Layer pattern: one place that resolves and checks identity, everything else trusts it rather than re-implementing the check.

5.5 Defense in depth: proxy.ts is UX, the DAL is the actual boundary

Section 4.2 already made this point for Server Actions specifically; it generalizes to the whole app. A redirect from proxy.ts for an unauthenticated visit to /(dashboard)/* is genuinely useful — it avoids a flash of protected UI and an extra round trip before the real check happens — but it is not the security boundary, for the same reason: a Server Action, a Route Handler, or a direct data-layer call can all be reached by paths that don't necessarily traverse the proxy the same way a full page navigation does. Treat proxy.ts's redirect as the fast, optimistic UX layer, and the Data Access Layer's per-call session check (getCurrentUser(), requireAuth()) as the actual, non-optional authorization boundary — every genuine access check belongs there, checked on every call, not assumed from how the user arrived at the route.

Senior interview defense — auth and route architecture

Q: Why can't you just read the session once in the root layout and pass it down as a prop to every page?

Two independent reasons, both load-bearing. First, under Cache Components a session read is a runtime-only operation — it can't be prerendered — so putting it at the top of a layout forces everything the layout wraps, {children} included, to become a dynamic hole instead of joining the static shell; you lose the performance benefit of Partial Prerendering for the entire section, not just the part that actually needs the session. Second, prop-drilling a session object through every intermediate layout and page couples all of them to that shape and defeats the point of colocating the check with the data access it's meant to protect. The pattern that avoids both — read once inside a <Suspense> boundary as far down the tree as the actual dependency requires, hand the unresolved promise through context, and let each consumer use() it independently — keeps the static shell intact everywhere the session genuinely isn't needed, and keeps the actual authorization check centralized in the Data Access Layer rather than scattered across every route that happens to render user-specific UI.

Part 6 — TanStack Query v5 as the client-side layer over RSC caching

6.1 Why bring a client cache into a framework that already has one

Cache Components (Part 3) solves server-side caching — what gets prerendered, what streams, what's shared across users. It says nothing about client-side concerns TanStack Query is actually built for: background refetching on window focus, optimistic client mutations with automatic rollback, deduplicating identical in-flight requests fired from multiple components, and a client-side cache that survives client-side navigations without a full server round trip. The two are complementary layers, not competing ones — the pattern is prefetching on the server, then handing the result to the client cache so the first render has zero loading state.

Server (RSC execution)
  |
  +--> Prefetch queries into a server-side QueryClient
  +--> dehydrate() the QueryClient's state into a plain serializable object
  +--> That object crosses the Flight stream like any other server-to-client prop
        |
        v
Browser (client hydration)
  |
  +--> <HydrationBoundary> unpacks it into the browser's QueryCache
  +--> Components read data immediately — zero layout shift, zero client spinner
  +--> Background staleness timers take over from here, refetching as needed

6.2 The server/browser QueryClient singleton — current pattern

@tanstack/react-query is current at 5.103.2 — still v5, no v6 exists. There's a real, newer export worth knowing about but not reaching for here: environmentManager — confirmed present at runtime and via its actual .d.ts — but it is not the getQueryClient() singleton pattern. It's a narrower API for overriding server/client detection in non-standard runtimes (a Service Worker, for instance, where window doesn't exist but the code should still behave like a browser):

declare const environmentManager: {
  isServer: () => boolean;
  setIsServer(isServerValue: boolean | (() => boolean)): void; // the override hook
};

The actual documented singleton pattern still uses the plain, separately-exported isServer boolean function, which environmentManager.isServer itself just delegates to for the common case:

// lib/query/get-query-client.ts
import { QueryClient, isServer } from '@tanstack/react-query';

function makeQueryClient(): QueryClient {
  return new QueryClient({
    defaultOptions: {
      queries: { staleTime: 60 * 1000 }, // avoid an immediate client refetch right after hydrating
    },
  });
}

// Browser-only singleton — stays `undefined` on the server, so the branch below
// always makes a fresh client per request there instead of reusing this module binding.
let browserQueryClient: QueryClient | undefined;

export function getQueryClient(): QueryClient {
  if (isServer) {
    // Server: a fresh client per call — see 6.4 for exactly why a shared one is a data leak
    return makeQueryClient();
  }
  if (!browserQueryClient) browserQueryClient = makeQueryClient();
  return browserQueryClient;
}

// lib/query/providers.tsx
'use client';
import { QueryClientProvider } from '@tanstack/react-query';
import type { ReactNode } from 'react';
import { getQueryClient } from './get-query-client';

export function QueryProviders({ children }: { children: ReactNode }) {
  // Calling getQueryClient() directly during render — not inside useState — is the
  // documented pattern here, because getQueryClient() is already singleton-safe on
  // its own; wrapping it in useState would just be redundant.
  const queryClient = getQueryClient();
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}

6.3 Prefetch on the server, hydrate on the client — and under Cache Components, behind Suspense

The obvious first version of this pattern — await queryClient.prefetchQuery(...) directly at the top of the page component — actually fails a real next build with cacheComponents: true on, because a prefetchQuery call reaches out to a live data source and that's exactly the class of runtime work Part 3 requires to sit behind a boundary:

Error: Route "/products": Next.js encountered uncached or runtime data during prerendering.

`fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()` accessed
outside of `<Suspense>` prevents the route from being prerendered, blocking the page load
and leading to a slower user experience.

Ways to fix this:
  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
  - [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"`
  - [block] Set `export const instant = false` to allow a blocking route

The fix — and the version to actually use — pushes the prefetch into its own async Server Component, wrapped in <Suspense> exactly like any other runtime read from Part 3:

// app/products/page.tsx
import { Suspense } from 'react';
import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
import { getQueryClient } from '@/lib/query/get-query-client';
import { QueryProviders } from '@/lib/query/providers';
import { ProductCatalogClient } from '@/components/products/ProductCatalog';
import { getProductCatalog } from '@/lib/api/products';

async function PrefetchedCatalog() {
  const queryClient = getQueryClient();

  await queryClient.prefetchQuery({
    queryKey: ['products', 'hardware'],
    queryFn: () => getProductCatalog('hardware'),
  });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <ProductCatalogClient category="hardware" />
    </HydrationBoundary>
  );
}

export default function ProductsPage() {
  return (
    <QueryProviders>
      <main className="container mx-auto p-8">
        <h1 className="text-3xl font-bold mb-6">Hardware Inventory</h1>
        <Suspense fallback={<p>Loading catalog…</p>}>
          <PrefetchedCatalog />
        </Suspense>
      </main>
    </QueryProviders>
  );
}

After this change, the route builds cleanly and shows as ◐ (Partial Prerender) in the route table — the page shell and heading are static, the catalog streams in behind its boundary. This is worth stating as its own rule, separate from Part 3's general one, because it's specifically the shape TanStack Query's own SSR-prefetch documentation doesn't spell out for a Cache Components project: the classic RSC-prefetch-plus-hydrate pattern needs its own <Suspense> boundary under cacheComponents: true — it can no longer sit unwrapped at the top of a page component the way pre-16 material shows it.

// components/products/ProductCatalog.tsx
'use client';

import { useQuery } from '@tanstack/react-query';
import { getProductCatalog } from '@/lib/api/products';
import type { Product } from '@/lib/types/products';

export function ProductCatalogClient({ category }: { category: string }) {
  const { data: products, error, isFetching } = useQuery<Product[]>({
    queryKey: ['products', category],
    queryFn: async () => {
      const res = await fetch(`/api/products?category=${category}`);
      return res.json();
    },
  });

  if (error) return <div className="text-red-600">Failed to load catalog.</div>;

  return (
    <div className="space-y-4">
      {isFetching && <span className="text-xs text-blue-500">Updating live inventory...</span>}
      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
        {products?.map((product) => (
          <div key={product.id} className="border p-4 rounded shadow">
            <h3 className="font-semibold text-lg">{product.title}</h3>
            <p className="text-gray-600">${product.price.toFixed(2)}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

Because the server already prefetched ['products', 'hardware'] and dehydrated it into the HydrationBoundary, the client's useQuery call with the same query key finds a warm cache entry on its very first render — queryFn doesn't actually run client-side at all until staleTime (60 seconds, from the shared client config above) elapses.

6.4 Two caching layers, one invalidation discipline

Running both Cache Components and TanStack Query means two independent caches exist simultaneously: Next.js's server-side 'use cache' store, and TanStack's browser-side QueryCache. Left uncoordinated, a revalidateTag on the server does nothing to the client's already-hydrated QueryCache, and a stale client cache can keep showing old data well past the point the server has fresh data ready to serve. Two disciplines keep them aligned rather than fighting each other: set TanStack's staleTime to roughly match the stale window of the corresponding cacheLife profile so the two caches agree on "how fresh is fresh," and — after any mutation that calls revalidateTag server-side — also call queryClient.invalidateQueries({ queryKey }) client-side inside the same transition, so the browser's cache is told explicitly rather than left to time out on its own separate schedule.

Never store new QueryClient() as a module-scoped variable on the server — this is the mistake the code above deliberately avoids with getQueryClient()'s branch. Both Node.js and Edge server runtimes reuse a warm module scope across multiple concurrent requests within the same process instance; a module-level QueryClient singleton would mean Request A's prefetched data — potentially including per-user data — gets dehydrated into Request B's response. Instantiating fresh inside the Server Component's own execution, per request, is what keeps requests from cross-contaminating each other's cache.

Part 7 — Core Web Vitals, verified against current thresholds

7.1 The three metrics, and what changed recently

As of today, Google's three Core Web Vitals and their "good" thresholds (measured at the 75th percentile of real-user visits) are:

The one genuinely dated fact still floating around in older material: FID (First Input Delay) is not a Core Web Vital anymore. INP fully replaced it as the responsiveness metric in March 2024, and that's still the current model — "INP is the successor metric to First Input Delay," per Google's own current documentation. If a resource still frames FID as a metric you're optimizing for, it's measuring the wrong thing: FID only captured the delay before the first interaction started processing, while INP captures the full duration of every interaction across the page's whole lifetime, which is both a stricter and a more representative measure of real responsiveness.

7.2 INP: task-splitting with scheduler.yield()

A JavaScript task running longer than roughly 50ms blocks the browser's single main thread — no paint, no input handling — until it finishes. That's the entire mechanism behind a poor INP score:

Long task, blocks the frame:
[Interaction] -> [========== 240ms of JS ==========] -> [Paint: INP 240ms, POOR]

Same work, yielded every ~40ms via scheduler.yield():
[Interaction] -> [Task 40ms] -> [Yield/Paint] -> [Task 40ms] -> [Task 40ms] -> ...

scheduler.yield() is real and shipped — not behind a flag — in Chrome/Edge 129+ and Firefox 142+. Safari has not implemented it, so it is genuinely not a Baseline-available API (Baseline requires all three major engines), and any production use needs a fallback for Safari users, not just a defensive check:

// components/performance/TaskSchedulerDemo.tsx
'use client';

import { useState } from 'react';

// TypeScript's shipped DOM lib does not yet include Scheduler/scheduler.yield types
// (an open request, microsoft/TypeScript#63016, was still unresolved as of this build) —
// `as any` here is the honest current state, not laziness. A narrower alternative is
// installing `@types/wicg-task-scheduling` and typing against that instead of a blanket cast.
async function yieldToMain(): Promise<void> {
  if ('scheduler' in window && 'yield' in (window as any).scheduler) {
    await (window as any).scheduler.yield();
  } else {
    // Safari fallback: a macrotask boundary via setTimeout still yields to the event loop,
    // just with lower priority guarantees than the native scheduler API provides.
    await new Promise((resolve) => setTimeout(resolve, 0));
  }
}

export function HighThroughputProcessor() {
  const [progress, setProgress] = useState<number>(0);
  const [isProcessing, setIsProcessing] = useState<boolean>(false);

  const processMassiveDataset = async () => {
    setIsProcessing(true);
    const items = Array.from({ length: 50000 }, (_, i) => i);

    for (let i = 0; i < items.length; i++) {
      Math.sqrt(items[i]!) * Math.atan2(items[i]!, 2);

      if (i % 250 === 0) {
        setProgress(Math.round((i / items.length) * 100));
        await yieldToMain(); // give the browser a chance to paint and handle input
      }
    }

    setProgress(100);
    setIsProcessing(false);
  };

  return (
    <div className="p-4 border rounded space-y-4">
      <button onClick={processMassiveDataset} disabled={isProcessing} className="px-4 py-2 bg-indigo-600 text-white rounded">
        {isProcessing ? 'Processing...' : 'Run Heavy Calculation'}
      </button>
      <div className="w-full bg-gray-200 h-4 rounded">
        <div className="bg-indigo-600 h-4 rounded" style={{ width: `${progress}%` }} />
      </div>
      <span>{progress}% complete</span>
    </div>
  );
}

7.3 LCP: getting the largest element painted early

Three causes account for almost every poor LCP score: a routing waterfall that delays even discovering the hero image, a missing priority/preload hint on an above-the-fold image, and network contention where the LCP image competes with render-blocking scripts for bandwidth.

// components/products/OptimizedHero.tsx
import Image from 'next/image';

export function OptimizedHero({ heroImageUrl, title }: { heroImageUrl: string; title: string }) {
  return (
    <div className="relative w-full h-[500px] overflow-hidden rounded-xl">
      <Image
        src={heroImageUrl}
        alt={title}
        fill
        priority // inserts <link rel="preload"> into the document head
        fetchPriority="high" // tells the browser's preload scanner to prioritize this byte-for-byte
        sizes="(max-width: 768px) 100vw, (max-width: 1200px) 80vw, 1200px" // stops mobile downloading a 4K asset
        className="object-cover"
        quality={80}
      />
      <div className="absolute inset-0 bg-black/40 flex items-center justify-center">
        <h1 className="text-4xl font-extrabold text-white">{title}</h1>
      </div>
    </div>
  );
}

7.4 CLS: reserving space before content exists

Layout shifts happen when an element is inserted into the flow without previously-reserved space, or when a downloaded web font swaps in with different metrics than its fallback. next/font fixes the second case specifically: fetched fonts are self-hosted at build time — confirmed current, "no requests are sent to Google by the browser when the user visits your site" — and the loader synthesizes a fallback @font-face with calculated ascent-override, descent-override, and size-adjust values that size-match the fallback to the real font, so the swap doesn't visibly reflow anything.

// app/layout.tsx
import { Inter } from 'next/font/google';
import './globals.css';

const inter = Inter({ subsets: ['latin'], display: 'swap', variable: '--font-inter' });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={inter.variable}>
      <body className="antialiased">{children}</body>
    </html>
  );
}

The other common CLS trigger is toggling display: none → display: block on a dynamically-revealed element: it's entirely absent from the layout tree while hidden, so inserting it shoves every following sibling down the page in a single frame. Reserve the space up front instead — a CSS aspect-ratio box, a fixed-height placeholder, or absolute positioning inside an already-sized parent — and animate opacity/visibility rather than display, so the element's footprint exists in the layout the whole time even when it's invisible.

7.5 Bundle size: barrel files and code splitting

Importing a single icon from a library's barrel index (import { Activity } from 'lucide-react') can force the bundler to parse every sibling export in that file if the library has side-effectful modules, even though only one icon is actually used:

// Forces evaluation of the whole barrel index in some bundler configurations
import { Activity } from 'lucide-react';

// Bypasses the barrel entirely — imports exactly one module
import Activity from 'lucide-react/dist/esm/icons/activity';

experimental.optimizePackageImports (Part 0.5) automates the second form for a configured package list, rewriting barrel imports into direct paths at compile time — still marked experimental and "not recommended for production" in the current docs, but the default list of packages it covers has grown well beyond icon libraries to include date-fns, lodash-es, @mui/material, recharts, and others.

For genuinely heavy, non-critical-path code — a charting library, a canvas-based visualization — next/dynamic splits it into its own client chunk, loaded only when actually rendered:

'use client';
import dynamic from 'next/dynamic';

const HeavyChart = dynamic(
  () => import('@/components/analytics/HeavyChart').then((mod) => mod.HeavyChart),
  { ssr: false, loading: () => <div className="h-[400px] w-full bg-gray-100 animate-pulse rounded" /> }
);

export function DashboardAnalytics() {
  return (
    <div className="p-6 border rounded-lg">
      <h2 className="text-xl font-bold mb-4">Traffic Performance</h2>
      <HeavyChart />
    </div>
  );
}

And for genuinely independent applications sharing a domain rather than one monolith, it's worth knowing the trade-off table between the three common multi-app strategies, since it's a recurring staff-level system design question:

+---------------------+-----------------------------------+-------------------------------------+
| Dimension           | Module Federation                 | Multi-Zones (Next.js)               |
+---------------------+-----------------------------------+-------------------------------------+
| Runtime             | Shared browser runtime            | Completely isolated applications    |
| Routing             | Single client SPA router          | Inter-app path routing (e.g. a CDN) |
| Shared state        | Global client-side memory         | Cookies, Web Storage, token sync    |
| Blast radius         | High — runtime version conflicts  | Low — independent deployments       |
| RSC compatibility   | Complex; splits Flight parsers    | Native — each zone runs full RSC    |
+---------------------+-----------------------------------+-------------------------------------+

Senior interview defense — Web Vitals diagnostics

Q: Why does toggling display: none to display: block cause a worse CLS score than other layout-shift causes, and how do you fix it structurally rather than case by case?

An element with display: none doesn't just render invisibly — it's removed from the layout algorithm entirely, contributing zero height, so every sibling below it lays out as if it doesn't exist. The instant it flips to display: block, the layout engine has to recompute the position of every subsequent element in the same frame, and that whole shift counts against CLS at once. The structural fix is to never let an element's presence in the layout tree depend on its visibility: reserve its footprint permanently (a min-height placeholder, a CSS aspect-ratio box, or absolute positioning inside an already-sized relative parent) and toggle opacity/visibility instead of display. Done this way, revealing the element is a paint-only change — the layout was already accounting for its space the whole time, so there's nothing left to shift.

Part 8 — Advanced TypeScript for production applications

8.1 any, unknown, and never — precisely, not just "unknown is safer"

These three sit at genuinely different places in the type system, and conflating them is the fastest way to fail a type-system question:

• any opts a value out of type checking entirely — it's not "the type is unknown," it's "stop checking." Every operation on an any value type-checks, including ones that will crash at runtime, and worse, any is contagious: assigning an any value to a typed variable silently widens that variable to any too, unless noImplicitAny and careful typing stop it at the boundary.
• unknown is the type-safe top type — anything can be assigned to it, but nothing can be read from it without a runtime narrowing check first (typeof, instanceof, a Zod safeParse, a user-defined type guard). This is exactly why catch (err: unknown) is the correct modern default over catch (err: any): you're forced to prove what err actually is before touching it.
• never is the bottom type — no value, not even null or undefined, is assignable to it except never itself. It's what a function that always throws or never returns is typed to produce, and — its most practically useful role — it's what a correctly-exhausted switch over a union collapses to, which is the mechanism behind compiler-enforced exhaustiveness below.

8.2 Discriminated unions with compiler-enforced exhaustiveness

export type Result<TData, TError = Record<string, string[]>> =
  | { readonly ok: true; readonly data: TData }
  | { readonly ok: false; readonly error: TError };

export function ok<TData>(data: TData): Result<TData, never> {
  return { ok: true, data };
}
export function fail<TError>(error: TError): Result<never, TError> {
  return { ok: false, error };
}

function renderActionFeedback<T>(result: Result<T>): string {
  switch (result.ok) {
    case true:
      return 'Operation successful.';
    case false:
      return `Operation failed: ${JSON.stringify(result.error)}`;
    default: {
      // If a third variant is ever added to the union, `result` here is no longer
      // assignable to `never`, and this line fails to compile — the exhaustiveness
      // check is a compile error, not a runtime assertion.
      const _exhaustiveCheck: never = result;
      return _exhaustiveCheck;
    }
  }
}

The mechanism worth being able to state out loud: after handling both case true and case false, TypeScript has narrowed result's type in the default branch down to the empty union — nothing is left it could possibly be — which is exactly never. Assigning it to a never-typed variable only type-checks because there's genuinely nothing left over; add a third state to the Result union without adding a case for it, and that assignment becomes a real type error at the exact place the switch fell out of sync with its own type, not a runtime surprise three files away.

8.3 Mapped types and key remapping

// Extracts the subset of keys whose value type extends Condition
export type FilterFlags<Base, Condition> = {
  [Key in keyof Base]: Base[Key] extends Condition ? Key : never;
}[keyof Base];

export type SubType<Base, Condition> = Pick<Base, FilterFlags<Base, Condition>>;

// Key remapping with the `as` clause — generates a differently-named key per original key
export type AsGetters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => Promise<T[K]>;
};
// AsGetters<{ name: string; age: number }> becomes
// { getName: () => Promise<string>; getAge: () => Promise<number> }

export type EntityValidators<T> = {
  [K in keyof T]: (value: T[K]) => boolean | string;
};

8.4 The built-in utility types, reimplemented — because understanding them beats memorizing them

An interviewer asking "implement Partial yourself" isn't testing whether you've memorized the standard library — they're checking whether you actually understand mapped types and conditional types, or just know the utility names.

// Partial<T>: every property becomes optional
type MyPartial<T> = { [K in keyof T]?: T[K] };

// Required<T>: every property becomes mandatory — the `-?` removes an optional modifier
type MyRequired<T> = { [K in keyof T]-?: T[K] };

// Readonly<T>: every property becomes immutable
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };

// Pick<T, K>: keep only the named keys
type MyPick<T, K extends keyof T> = { [P in K]: T[P] };

// Omit<T, K>: drop the named keys — implemented in terms of Pick and Exclude
type MyExclude<T, U> = T extends U ? never : T;
type MyOmit<T, K extends keyof any> = MyPick<T, MyExclude<keyof T, K>>;

// Record<K, V>: a dictionary type from a union of keys to one value type
type MyRecord<K extends keyof any, V> = { [P in K]: V };