DEV Community: jsmanifest

Claude Code Diff Verification in 2026: How to Make Your Agent Assert Its Own Edits Did Not Break the Build

jsmanifest — Sat, 07 Nov 2026 06:07:30 +0000

Claude Code Diff Verification in 2026: How to Make Your Agent Assert Its Own Edits Did Not Break the Build

Developers who ship code written by Claude Code in 2026 face a gap between what the agent claims it did and what actually changed. The agent generates edits, reports success, and stops. The build might be broken, tests might fail silently, or type errors might sit unnoticed until you run the check yourself. The failure mode looks like this: Claude edits three files, says the feature is done, and you merge it into main before discovering the auth middleware now crashes on every request because a required field is missing.

Problem flow showing Claude Code reporting success while build is broken

The Claude Code documentation states that Claude stops when the work looks done, and if it has nothing to run that tells it whether the work actually is done, it has no way to verify its own changes. The solution is a post-edit verification hook that runs git diff, tests, and type checks before the agent finishes its turn. When the hook exits with code 2, Claude Code sends the errors back to Claude, which fixes the problem and runs the check again.

Solution flow showing Stop hook blocking turn end until typecheck passes

This post shows how to build verification into every agent session so the agent asserts its own edits before you approve them.

Key Takeaways

Claude Code cannot verify its own changes without an executable check (tests, type check, build command, or linter) that returns pass or fail.
A Stop hook that exits with code 2 blocks the turn from ending and sends errors back to Claude, forcing it to fix the problem before claiming success.
The verification pattern has four layers: in-prompt requests (agent decides when satisfied), /goal conditions (checked after every turn), Stop hooks (enforced by the harness), and independent subagent review.
Manual review after the fact catches what hooks miss, but hook-based verification catches what manual review skips because the diff looked small.
Production workflows combine pre-commit hooks (format, lint), Stop hooks (typecheck, unit tests), and CI (integration tests, security scans) at different checkpoints in the pipeline.

Understanding What Claude Code Can and Cannot Verify on Its Own

Claude Code has access to every tool a developer has. It can run git diff, execute test suites, and read compiler output. The gap is not in capability but in awareness. When Claude finishes editing, it decides the turn is done based on whether the work matches the prompt. Without an executable check that returns a pass or fail signal, the agent has no feedback loop that tells it whether the code actually works.

Claude Code verification capabilities showing what it can read versus what it can enforce

The overview documentation explains that Claude Code reads your codebase, edits files, runs commands, and integrates with development tools. Reading and running are not the problem. The problem is that running a check is optional from the agent's perspective unless the check is mandatory in the workflow. A developer who asks Claude to "add the rate limiter and make sure tests pass" gets an agent that decides for itself when it is satisfied. If the tests pass on the first try, great. If the agent thinks they passed but did not read the full output, the session ends with failing tests.

The four verification layers differ in who decides when the work is done. At the weakest layer, the agent decides based on whether it thinks it satisfied the prompt. At the strongest layer, the harness (Claude Code itself) decides based on whether a script exits with code 0. The layers are:

Layer	Decision maker	When it runs	Override mechanism
In-prompt request	Agent	When agent chooses	Agent decides satisfaction
`/goal` condition	Separate model	After every turn	Keeps agent working until condition met
Stop hook	Claude Code harness	Before turn ends	Exit code 2 blocks stop
Subagent review	Independent subagent	On demand	Reports findings back to main session

The in-prompt request is the baseline. Asking Claude to "run tests after and keep going until they pass" works for any task today with no setup. The agent runs the tests, reads the output, and decides whether to keep going. This catches obvious failures but relies on the agent's judgment about what output means success.

A /goal condition sets a target that a separate model checks after every turn. The best practices documentation states that goals matter for long background runs, where Claude sometimes ends a turn with a progress summary while items are still open, and the goal sends it back. The condition is checked by a model, not a script, so it interprets natural language criteria like "all tests in tests/auth pass and lint is clean."

A Stop hook runs a shell command whenever Claude tries to end its turn. If the command exits with code 2, the turn does not end. The hook is enforced by the Claude Code harness, so the typecheck has to pass before the session can finish. This is the layer where verification becomes mandatory rather than requested.

A subagent reviewer gets a fresh conversation with no memory of how the code was written. The code review documentation describes /code-review, which reviews the diff in a subagent that never saw your conversation. The subagent is not swayed by the reasoning that produced the code, so it catches mistakes the main agent might rationalize away.

Verification layers diagram

The gap in awareness happens because the agent treats "run the tests" as a tool call, not as a verification gate. When you ask Claude to run tests, it executes the command, reads the output, and continues based on what it sees. If the output is long and the agent decides to summarize it rather than reading every line, it might miss a failure buried in the middle. The Stop hook closes this gap by making the check mandatory. The agent cannot end the turn until the script exits with code 0.

Building a Post-Edit Verification Hook That Runs git diff, Tests, and Type Checks

A Stop hook is a shell command defined in .claude/settings.json that runs before Claude Code allows a turn to end. If the command exits with code 0 or 1, the turn ends normally. If it exits with code 2, Claude Code sends the command's stderr back to Claude and blocks the stop. The agent gets the error output and continues working until the check passes.

The minimal Stop hook that enforces type checking looks like this:

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "pnpm tsc --noEmit 1>&2 || exit 2"
      }
    ]
  }
}

The command runs pnpm tsc --noEmit and redirects stdout to stderr with 1>&2 so all output goes to stderr. If tsc fails, the command exits with code 2, which tells Claude Code to block the stop and send the compiler errors back to Claude. Claude reads the errors, fixes the type issues, and the Stop hook runs again. This loop continues until tsc exits with code 0.

The hooks documentation states that if the hook blocks eight stops in a row with no tool call between them, Claude Code overrides the next block and ends the turn. The default cap is eight. To raise it, set the CLAUDE_CODE_STOP_HOOK_BLOCK_CAP environment variable.

A more complete Stop hook that combines type checking, linting, and unit tests looks like this:

// .claude/verify.sh
#!/bin/bash
set -e

echo "Running verification checks..." >&2

# Type check
pnpm tsc --noEmit 2>&1 | tee >(cat >&2)
if [ ${PIPESTATUS[0]} -ne 0 ]; then
  echo "Type check failed" >&2
  exit 2
fi

# Lint
pnpm eslint src --max-warnings 0 2>&1 | tee >(cat >&2)
if [ ${PIPESTATUS[0]} -ne 0 ]; then
  echo "Lint failed" >&2
  exit 2
fi

# Unit tests
pnpm test:unit 2>&1 | tee >(cat >&2)
if [ ${PIPESTATUS[0]} -ne 0 ]; then
  echo "Unit tests failed" >&2
  exit 2
fi

echo "All checks passed" >&2
exit 0

The script runs three checks in sequence and exits with code 2 if any fails. The tee >(cat >&2) construct sends output to both stdout (for the tee) and stderr (for Claude Code), so Claude sees the full output when a check fails. The script exits early on the first failure, so Claude gets immediate feedback about what broke without waiting for the remaining checks.

The settings file references the script:

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "bash .claude/verify.sh"
      }
    ]
  }
}

The Stop hook runs every time Claude tries to end a turn, so it catches mistakes before you see the changes. When Claude edits a file and introduces a type error, the Stop hook blocks the stop, sends the compiler error back, and Claude fixes it. The fix might introduce a lint warning, which blocks the next stop and sends Claude back again. This loop continues until all three checks pass.

The cost of this approach is token usage. Every blocked stop sends the full error output back to Claude, which extends the conversation. A type error that takes three attempts to fix adds three error messages to the context. For short error messages this is negligible. For long test output or verbose compiler errors, it can add thousands of tokens per session. The best practices documentation recommends asking for short summaries back when subagents run long checks, and the same principle applies to Stop hooks.

The verification script can also run git diff to show Claude what changed. A diff check that looks for common mistakes might look like this:

// .claude/diff-check.sh
#!/bin/bash

DIFF=$(git diff HEAD)

if echo "$DIFF" | grep -q "TODO"; then
  echo "Diff contains TODO markers" >&2
  exit 2
fi

if echo "$DIFF" | grep -q "console.log"; then
  echo "Diff contains console.log statements" >&2
  exit 2
fi

if echo "$DIFF" | grep -q "debugger"; then
  echo "Diff contains debugger statements" >&2
  exit 2
fi

exit 0

This script fails the Stop hook if the diff contains TODO markers, console.log statements, or debugger statements. The check catches debugging code that should have been removed before the session ended. The script is simplistic (it flags legitimate uses of console.log in logging utilities), but it demonstrates the pattern. A production version would use a proper parser or limit the check to specific directories.

The Stop hook is a blunt instrument. It blocks every stop attempt, which means it blocks even when Claude is legitimately done and you want to review the changes yourself. The settings reference does not document a way to disable the Stop hook mid-session, so the workaround is to exit the session or temporarily modify .claude/settings.json. For workflows where you want manual review before auto-fixing, the Stop hook might be too aggressive.

Assertion Patterns: Making the Agent Verify Its Own Changes Before You Approve

The verification pattern has four checkpoints where the agent can assert its own changes. The checkpoints differ in what they cost and what they catch. Combining them gives you defense in depth: the in-prompt request catches obvious breaks, the Stop hook enforces correctness, and the independent review catches logic errors the tests missed.

Verification pattern execution flow showing progression from edit through multiple checks

The first checkpoint is the in-prompt request. When you ask Claude to "add pagination to the search endpoint and verify the tests pass," Claude makes the changes, runs the test suite, reads the output, and reports what it saw. This catches failures that produce clear error messages. It does not catch failures where the agent misinterprets the output or decides a warning is not worth fixing.

The second checkpoint is the /goal condition. Setting a goal with /goal all unit tests pass and no lint warnings gives Claude a target that a separate model checks after every turn. The best practices documentation explains that goals matter for background sessions, where Claude might end a turn early while work is still pending. The goal model sees the conversation and the goal statement and decides whether the goal is met. If not, Claude continues.

The third checkpoint is the Stop hook. The hook enforces the check at the harness level, so the agent cannot bypass it. A Stop hook that runs pnpm tsc --noEmit 1>&2 || exit 2 blocks every stop attempt until the typecheck passes. The agent sees the compiler errors and fixes them before you see the changes. This checkpoint catches type errors, lint violations, and test failures that the agent might have missed or misinterpreted.

The fourth checkpoint is an independent review. Running /code-review in the session sends the diff to a fresh subagent that reviews the changes without having seen how they were written. The subagent looks for logic errors, missing edge cases, and security issues that tests and type checks do not catch. The review comes back into your session, where Claude can fix the problems before you approve the changes.

The pattern that catches the most problems combines all four checkpoints:

Ask Claude to "implement the feature and verify tests pass" (in-prompt request)
Set /goal feature complete, all tests pass, no type errors (automatic goal check)
Add a Stop hook that runs typecheck and lint (enforced by harness)
Run /code-review before merging (independent perspective)

Each checkpoint has a different failure mode. The in-prompt request fails when the agent skips the check or misinterprets the output. The goal check fails when the goal statement is ambiguous or the goal model is too lenient. The Stop hook fails when the script itself has bugs or when the check is too strict (blocking legitimate work). The independent review fails when the subagent lacks context or when the diff is too large to review effectively.

The cost-benefit tradeoff differs by project. A small prototype where you are the only developer might use only the in-prompt request. A production codebase with multiple contributors might use all four checkpoints. The Stop hook has the best cost-to-value ratio: it costs almost nothing to set up (one file in .claude/settings.json) and it catches every type error and test failure before you see the changes.

The assertion pattern also applies to changes you make yourself. A Stop hook that runs on every turn also runs when you edit a file manually and then ask Claude to continue. The hook catches your mistakes as well as Claude's mistakes. This makes the Stop hook a form of continuous verification that runs throughout the session, not just when Claude is working.

Comparison: Manual Review vs Hook-Based Verification vs Full CI Integration

The three approaches to verifying agent-written code differ in when they catch problems, what they cost, and how much they trust the agent. Manual review catches problems after the session ends. Hook-based verification catches problems during the session before you see the changes. Full CI integration catches problems after you merge but before production.

Comparison of verification approaches showing when each catches problems

Manual review happens after the session ends. You run git diff, look at the changes, and check for problems. This approach catches mistakes that automated checks miss: logic errors, missing edge cases, and changes that work but do not match the requirements. The failure mode is that you skip the review because the diff looks small, or you skim it and miss a subtle bug. Manual review also happens after the agent session, so fixing problems means reopening the conversation or making the fix yourself.

Approach	Catch time	Cost	What it catches	What it misses
Manual review	After session	Developer time	Logic errors, requirements mismatch	Skipped reviews, subtle bugs
Hook verification	During session	Token usage for fixes	Type errors, test failures, lint	Logic errors, integration issues
Full CI	After merge	CI compute time	Integration failures, security	Problems caught too late

Hook-based verification happens during the session before you see the changes. The Stop hook runs checks and blocks the turn from ending until they pass. This approach catches type errors, test failures, and lint violations before you start the review. The failure mode is that the hook is too strict (blocking legitimate work) or too lenient (missing problems that matter). Hook verification also costs tokens: every blocked stop sends error output back to Claude, extending the conversation.

Full CI integration happens after you merge the code. The CI pipeline runs the complete test suite, integration tests, and security scans. This approach catches problems that unit tests and type checks miss: integration failures, environment-specific bugs, and security vulnerabilities. The failure mode is that problems are caught late, after you already approved the changes and merged them to main. Fixing a CI failure means reverting the merge or opening a new PR.

The three approaches are not mutually exclusive. A complete verification workflow combines them at different checkpoints:

Stop hook runs during the session (type check, lint, unit tests)
Manual review happens before merge (logic, requirements, security)
CI runs after merge (integration tests, E2E tests, security scans)

The Stop hook catches fast, cheap checks that can run in seconds. Manual review catches problems that need human judgment. CI catches expensive checks that need a clean environment or external services. Each layer catches what the previous layer missed.

The Claude Code CI documentation covers how to integrate Claude Code with GitHub Actions and GitLab CI/CD for automated PR reviews and issue triage. The CI integration runs Claude Code in a fresh environment with no session history, so it catches problems that the local session missed because of stale state or local configuration.

The cost structure differs by approach. Manual review costs developer time. A five-minute review per PR adds up when you ship ten PRs per day. Hook verification costs tokens. A Stop hook that blocks three times and sends 500 tokens of error output back each time adds 1,500 tokens to the session. CI costs compute time. Running the full test suite on every merge takes minutes and costs money on hosted CI services.

The tradeoff is between catching problems early (when they are cheap to fix) and catching problems thoroughly (when you have complete information). A Stop hook that runs unit tests catches problems in seconds, but it might miss integration issues that only show up when the feature runs in production. CI catches integration issues, but by then you already merged the code and the fix is a new PR instead of an iteration in the same session.

Production Patterns: Pre-Commit Checks, Test Suites, and What to Auto-Accept

Production workflows layer verification checks at different points in the development pipeline. Pre-commit hooks run before code enters version control. Stop hooks run during agent sessions. CI runs before code reaches production. Each layer has different criteria for what to check and what to auto-accept.

Production verification pipeline showing checks at each stage

Pre-commit hooks run before git commit succeeds. A typical pre-commit hook runs formatters (Prettier, Black), linters (ESLint, Pylint), and static analysis. These checks are fast (under one second) and deterministic (they always produce the same result for the same input). Pre-commit hooks are auto-fixing: if the formatter changes a file, the commit includes the formatted version. The hook fails only if the linter finds an error the formatter cannot fix.

Stop hooks run during Claude Code sessions before the agent can end a turn. A typical Stop hook runs type checks (tsc --noEmit, mypy), unit tests (pnpm test:unit, pytest tests/unit), and linters. These checks are slower than pre-commit hooks (seconds to tens of seconds) but still fast enough to run on every stop attempt. Stop hooks are not auto-fixing: they send errors back to Claude, which fixes the code and tries again.

CI runs after code merges to a branch or opens a PR. A typical CI pipeline runs integration tests, end-to-end tests, security scans (Snyk, Dependabot), and deployment to staging. These checks are slow (minutes to tens of minutes) and might depend on external services (databases, APIs, cloud resources). CI is blocking: a failed CI run prevents the PR from merging or the code from deploying.

The pattern that works in production is:

Pre-commit: format, lint (auto-fixing, under one second)
Stop hook: typecheck, unit tests (agent-fixing, under ten seconds)
CI: integration tests, security scans, staging deploy (blocking, minutes)

Each layer checks what the previous layer cannot catch or cannot afford to run. Pre-commit hooks catch formatting and obvious lint errors. Stop hooks catch type errors and unit test failures. CI catches integration issues and security vulnerabilities.

Production pipeline diagram

What to auto-accept depends on the risk of the change and the cost of being wrong. A formatting change has low risk (it does not change behavior) and low cost (you can revert it in one commit), so auto-accepting formatted code is safe. A database migration has high risk (it can lose data) and high cost (reverting requires a rollback), so auto-accepting migrations is dangerous.

The auto-accept criteria differ by check:

Check	Auto-accept?	Why
Prettier format	Yes	Deterministic, no behavior change
ESLint auto-fix	Yes	Simple transforms, rarely breaks code
Type errors fixed by agent	Conditional	Review if change is large or risky
Unit tests passing	No	Passing tests do not mean correct behavior
Integration tests passing	No	Tests might pass with wrong behavior

The conditional case (type errors fixed by agent) depends on the scope of the change. If Claude fixes a type error by adding a type annotation, that is low risk and can auto-accept. If Claude fixes a type error by refactoring a function, that is higher risk and needs review. The Stop hook does not distinguish between these cases, so the review step happens manually.

The tests-passing case is subtle. A Stop hook that blocks until unit tests pass does not guarantee the code is correct. It only guarantees the tests passed. If the tests are incomplete or if the tests pass for the wrong reason, the Stop hook lets bad code through. The independent review checkpoint catches this: a subagent that reviews the diff can spot missing test cases even when existing tests pass.

A realistic Stop hook configuration for a TypeScript backend might look like this:

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "pnpm tsc --noEmit 1>&2 || exit 2"
      },
      {
        "type": "command",
        "command": "pnpm test:unit --passWithNoTests 1>&2 || exit 2"
      }
    ]
  }
}

This configuration runs two checks: tsc --noEmit for type checking and pnpm test:unit for unit tests. The --passWithNoTests flag makes the test command succeed even if no tests ran, which prevents the Stop hook from blocking when you are working on a feature that does not have tests yet. Both commands redirect output to stderr so Claude sees the full error messages when a check fails.

The cost control documentation covers how to manage token usage in production workflows where Stop hooks run frequently. The main cost-control pattern is to keep Stop hook checks fast and focused: run type checks and unit tests, but not integration tests or security scans. Save the expensive checks for CI, where they run once per merge instead of once per stop attempt.

The verification pattern also applies to changes that are not code. A Stop hook that runs markdownlint catches formatting errors in documentation. A Stop hook that runs jsonlint catches syntax errors in config files. The pattern is the same: define a check that returns pass or fail, put it in a Stop hook, and let the agent fix failures before the session ends.

Frequently Asked Questions

What happens if the Stop hook blocks eight times in a row?

Claude Code overrides the block and ends the turn. The default cap is eight blocked stops with no tool call between them. Set CLAUDE_CODE_STOP_HOOK_BLOCK_CAP higher if you need more attempts, but if the agent cannot fix the problem in eight tries, the issue is usually with the check itself (too strict) or the task (too complex for the agent).

Can I disable the Stop hook for one session without editing settings.json?

The hooks documentation does not document a way to disable a Stop hook mid-session. The workaround is to comment out the hook in .claude/settings.json, restart the session, or use a different worktree that does not have the hook configured. For workflows where you want manual control, skip the Stop hook and use in-prompt requests instead.

Should the Stop hook run the full test suite or only unit tests?

Run only fast tests (under ten seconds). A Stop hook that takes 30 seconds to run blocks the agent for 30 seconds on every stop attempt, which adds up to minutes of wait time per session. Save slow tests (integration tests, E2E tests) for CI. The best practices documentation recommends running checks that come back pass or fail quickly.

Does the Stop hook work with subagents and background sessions?

Yes. The Stop hook runs in every session, including subagent sessions and background sessions. A subagent that edits files and tries to stop gets blocked by the same Stop hook the main session uses. This means background tasks self-validate before finishing, so you can trust the results without reviewing every session individually.

What if the Stop hook itself has a bug?

The session hangs. If the Stop hook script has a syntax error or references a command that does not exist, every stop attempt fails and Claude cannot end the turn. The fix is to exit the session, fix the script in .claude/settings.json, and restart. Test Stop hook scripts outside Claude Code first (run bash .claude/verify.sh yourself) to catch script bugs before they block a session.

Conclusion: Trust but Verify

The gap between what Claude Code claims and what actually works closes when the agent can run the same checks a developer would run. A Stop hook that enforces type checking, linting, and unit tests turns agent sessions into self-validating workflows. The agent makes changes, the hook blocks the turn until checks pass, and the agent fixes failures before you see the changes. What you get is code that passed verification before it reached your review, which means the review focuses on logic and requirements instead of catching type errors and test failures.

The production pattern layers verification at three checkpoints: pre-commit hooks that auto-fix formatting, Stop hooks that agent-fix correctness, and CI that blocks bad merges. Each layer catches what the previous layer cannot afford to run. The cost is token usage for Stop hook iterations and CI compute time for integration tests. The payoff is code that self-validates as it is written instead of breaking when you run it.

Start with a Stop hook that runs tsc --noEmit 1>&2 || exit 2 in .claude/settings.json. Add unit tests to the hook once you have a fast test suite. Save integration tests and security scans for CI. The verification pattern works because it gives Claude something executable that returns pass or fail, and that executable check is what closes the awareness gap.

Sources

Week 30 · July 20–24, 2026 - Claude Code Docs

TypeScript `const` Enums Are Deprecated: What to Migrate to and Why the Compiler Team Made the Call

jsmanifest — Fri, 06 Nov 2026 06:06:06 +0000

TypeScript `const` Enums Are Deprecated: What to Migrate to and Why the Compiler Team Made the Call

TypeScript const enums promised zero-runtime cost for constant values, but they broke isolated module compilation and caused runtime errors downstream. The compiler team deprecated them not because of theoretical purity, but because they caused production failures when developers mixed const enums with modern build tools like esbuild, swc, and Vite. A const enum in a library's .d.ts file becomes a landmine: the consuming project inlines values at compile time but ships code that expects those enum objects to exist at runtime. When versions drift between compile and runtime dependencies, conditionals take the wrong branch and silent data corruption follows.

The problem diagram shows the failure path:

const enum compilation breaks when compiler cannot see declaration file

The solution eliminates compile-time inlining and removes the dependency on cross-module information:

union types with as const provide type safety without runtime dependencies

TypeScript const enum deprecation warning in compiler output

The migration path depends on whether the enum appears in a library or application code. Libraries must remove const enums entirely because they cannot control how downstream consumers compile their code. Application code can migrate incrementally, starting with high-risk modules that interact with external dependencies.

Key Takeaways

Const enums fail in isolated module compilation because the compiler cannot access cross-file information to inline values, causing unresolved imports at runtime.
The TypeScript team deprecated const enums to prevent version drift bugs where compile-time values differ from runtime values, leading to wrong conditional branches and data corruption.
Union types with as const provide equivalent type safety without runtime objects, making them compatible with modern build tools that compile modules in isolation.
Libraries shipping .d.ts files with const enums force downstream consumers to disable isolatedModules, breaking compatibility with esbuild, swc, and other fast compilers.
The preserveConstEnums compiler option emits runtime objects but defeats the original zero-cost promise and creates inconsistent behavior between development and production builds.

The Technical Problems With Const Enums

Const enums operate by replacing references with literal values at compile time. When the compiler encounters Direction.Up, it substitutes the numeric literal 0 directly into the emitted JavaScript. This inlining removes the enum object from the output entirely, which sounds efficient until modules compile independently.

The TypeScript documentation on enums explains that const enums "are completely removed during compilation" and "members are inlined at use sites." The removal happens because the compiler treats the enum as a macro expansion rather than a runtime value.

const enum inlining requires cross-module visibility to substitute values

The inlining breaks when the compiler processes files in isolation. Modern build tools compile TypeScript modules independently to maximize parallelism. A module that imports a const enum from another file cannot inline the values because it never reads the declaring file. The import statement stays in the output JavaScript, referencing an enum object that was never emitted.

The failure mode appears when libraries publish ambient const enums in declaration files. A library's .d.ts file declares the const enum shape but provides no implementation. The consuming project's compiler sees the declaration and inlines values based on that snapshot. At runtime, the library's JavaScript code contains no enum object because the const modifier stripped it during the library's build. The consuming code executes with hardcoded values that may not match the library's current version.

Version drift amplifies the problem. A project compiles against version 1.2 of a library, inlining Status.Active = 5. The deployment runtime loads version 1.3 where Status.Active changed to 7. The compiled code still checks if (status === 5) but the library now returns 7 for active status. The conditional silently fails and the application continues executing on the wrong path.

The isolatedModules compiler option exists specifically to catch these situations. When enabled, TypeScript rejects code patterns that only work with whole-program compilation. The documentation states that isolatedModules "is fundamentally incompatible with ambient const enums" because inlining requires seeing the enum definition.

Build tools choose isolated module compilation for speed. The TypeScript 5.0 release notes introduced the verbatimModuleSyntax option to make module semantics explicit and predictable across different compilers. The new option removes import elision and treats all module syntax literally, which makes const enum inlining impossible.

The TypeScript team deprecated const enums because they require whole-program knowledge in an ecosystem moving toward isolated compilation. The tradeoff between zero-cost abstractions and compilation speed tilted decisively toward speed when developers started hitting production failures from version drift.

How Const Enums Break in Isolated Module Compilation

The breakage becomes concrete when examining actual compiler output. A const enum in one file and an import in another produces different JavaScript depending on whether the compiler processes them together or separately.

// constants.ts
export const enum Direction {
  Up = 0,
  Down = 1,
  Left = 2,
  Right = 3,
}

// movement.ts
import { Direction } from "./constants";

export function move(direction: Direction): string {
  switch (direction) {
    case Direction.Up:
      return "moving up";
    case Direction.Down:
      return "moving down";
    case Direction.Left:
      return "moving left";
    case Direction.Right:
      return "moving right";
  }
}

When TypeScript compiles both files together, the output for movement.ts replaces enum references with literals:

// movement.js (whole-program compilation)
export function move(direction) {
  switch (direction) {
    case 0: // Direction.Up
      return "moving up";
    case 1: // Direction.Down
      return "moving down";
    case 2: // Direction.Left
      return "moving left";
    case 3: // Direction.Right
      return "moving right";
  }
}

The constants.ts file emits nothing because the const enum disappears entirely. The JavaScript output contains no Direction object and no export statement. This works only because the compiler inlined the values before generating code.

When a build tool compiles movement.ts in isolation, it cannot inline the values because it never reads constants.ts. The output keeps the import statement:

// movement.js (isolated module compilation)
import { Direction } from "./constants";

export function move(direction) {
  switch (direction) {
    case Direction.Up:
      return "moving up";
    case Direction.Down:
      return "moving down";
    case Direction.Left:
      return "moving left";
    case Direction.Right:
      return "moving right";
  }
}

At runtime, the JavaScript engine tries to import Direction from constants.js. That file exports nothing because the const enum was stripped during the library's compilation. The import fails with an unresolved module specifier or imports an undefined value, causing the switch statement to match no cases.

Example of runtime error from const enum in isolated compilation

The isolatedModules documentation calls out this specific failure. The compiler option enables a check that rejects const enum imports from external modules. The error message reads: "Cannot access ambient const enums when the '--isolatedModules' flag is provided."

The ambient qualifier matters. An ambient const enum appears in a declaration file without an implementation. Libraries ship .d.ts files containing const enum declarations, expecting consumers to inline the values. The consumer's compiler sees only the declaration and has no way to verify the values match the library's runtime code.

The fix requires either removing the const modifier to emit a runtime object, or migrating to an alternative that works without cross-file inlining. The next sections cover both migration paths and when to use each one.

Migration Path 1: Union Types With as const

Union types combined with the as const assertion replicate const enum type safety without emitting runtime code. The pattern defines an object with as const to create literal types, then extracts a union type from the object's values.

// Before: const enum
const enum Direction {
  Up = 0,
  Down = 1,
  Left = 2,
  Right = 3,
}

// After: union type with as const
const Direction = {
  Up: 0,
  Down: 1,
  Left: 2,
  Right: 3,
} as const;

type Direction = typeof Direction[keyof typeof Direction];

The as const assertion tells the compiler to infer the most specific type possible. Without it, TypeScript widens the type to number. With as const, each property gets its exact literal type: 0, 1, 2, 3. The type extraction typeof Direction[keyof typeof Direction] produces the union 0 | 1 | 2 | 3.

union type extraction flow from const object to type parameter

Functions that previously accepted the enum type now accept the extracted union type. The type safety remains identical:

function move(direction: Direction): string {
  switch (direction) {
    case Direction.Up:
      return "moving up";
    case Direction.Down:
      return "moving down";
    case Direction.Left:
      return "moving left";
    case Direction.Right:
      return "moving right";
  }
}

move(Direction.Up); // type-safe
move(Direction.Down); // type-safe
move(5); // error: Argument of type '5' is not assignable to parameter of type '0 | 1 | 2 | 3'

The TypeScript compiler enforces that callers pass only the valid direction values. The compiled JavaScript contains a runtime object with the direction properties, making it compatible with isolated module compilation:

const Direction = {
  Up: 0,
  Down: 1,
  Left: 2,
  Right: 3,
};

function move(direction) {
  switch (direction) {
    case Direction.Up:
      return "moving up";
    case Direction.Down:
      return "moving down";
    case Direction.Left:
      return "moving left";
    case Direction.Right:
      return "moving right";
  }
}

The object exists at runtime, so imports resolve correctly even when modules compile in isolation. The tradeoff is a small runtime cost: the object occupies memory and requires a property access instead of using an immediate literal value. For most applications, the cost disappears in the noise of other object allocations.

String-valued enums migrate the same way:

// Before: string const enum
const enum LogLevel {
  Debug = "DEBUG",
  Info = "INFO",
  Warn = "WARN",
  Error = "ERROR",
}

// After: union type with as const
const LogLevel = {
  Debug: "DEBUG",
  Info: "INFO",
  Warn: "WARN",
  Error: "ERROR",
} as const;

type LogLevel = typeof LogLevel[keyof typeof LogLevel];

The union type becomes "DEBUG" | "INFO" | "WARN" | "ERROR", which the compiler treats as distinct literal types. The TypeScript handbook on enums notes that "an object with as const could suffice" for many enum use cases, and this migration proves the point.

The pattern works in libraries because it requires no special compiler behavior. A library exports the const object and the type, and consumers import both normally. No inlining happens and no cross-file dependencies exist. The module system handles the runtime object like any other export.

Migration Path 2: Plain const Objects

When type safety matters less than convenience, a plain const object without type extraction provides a simpler migration. The object still gets as const to freeze its type, but no union type extraction happens.

// Before: const enum
const enum HttpStatus {
  OK = 200,
  Created = 201,
  BadRequest = 400,
  Unauthorized = 401,
  NotFound = 404,
}

// After: plain const object
const HttpStatus = {
  OK: 200,
  Created: 201,
  BadRequest: 400,
  Unauthorized: 401,
  NotFound: 404,
} as const;

Functions accept number instead of the specific union type:

function handleResponse(status: number): void {
  if (status === HttpStatus.OK) {
    console.log("Success");
  } else if (status === HttpStatus.NotFound) {
    console.log("Resource not found");
  }
}

The compiler allows any number, not just the defined status codes. This loses type safety but matches the original const enum behavior more closely. Const enums with numeric values did not prevent passing arbitrary numbers either, they just provided autocomplete for the defined constants.

plain const object migration removes type extraction step

The JavaScript output includes the object exactly as written:

const HttpStatus = {
  OK: 200,
  Created: 201,
  BadRequest: 400,
  Unauthorized: 401,
  NotFound: 404,
};

function handleResponse(status) {
  if (status === HttpStatus.OK) {
    console.log("Success");
  } else if (status === HttpStatus.NotFound) {
    console.log("Resource not found");
  }
}

This pattern suits internal application code where the team controls all usage sites. The lack of type constraints speeds up refactoring because changing a value requires updating only the object definition, not every function signature that references it.

Libraries should prefer the union type approach. Exporting a plain object without extracted types gives consumers no guidance about valid values. The autocomplete shows the object properties but the type system accepts anything, leading to runtime errors when callers pass invalid values.

The const object approach also handles computed enum values better than union types. Const enums with expressions become cumbersome to migrate to unions:

// Before: const enum with computed values
const enum Permissions {
  None = 0,
  Read = 1 << 0,
  Write = 1 << 1,
  Execute = 1 << 2,
  ReadWrite = Read | Write,
}

// After: plain const object preserves expressions
const Permissions = {
  None: 0,
  Read: 1 << 0,
  Write: 1 << 1,
  Execute: 1 << 2,
  ReadWrite: (1 << 0) | (1 << 1),
} as const;

Extracting a union type here requires computing the expression results manually (1 | 2 | 4 | 3), which defeats the purpose of the named constants. The plain object keeps the expressions readable and maintains the relationship between combined flags.

Const Enums vs Regular Enums vs Modern Alternatives

The three approaches differ in runtime presence, type safety, and compatibility with modern build tools. The table summarizes the key distinctions:

Feature	Const Enum	Regular Enum	Union Type with as const	Plain const Object
Runtime object	No	Yes	Yes	Yes
Type safety	Compile-time only	Full	Full	None
Isolated modules	Breaks	Works	Works	Works
Bundle size impact	None	Small object	Small object	Small object
Reverse mapping	No	Yes	No	No
Library-safe	No	Yes	Yes	Conditional

comparison flowchart showing const enum versus modern alternatives

Regular enums emit a runtime object that supports reverse mapping. Numeric enums create a two-way mapping between names and values:

enum Direction {
  Up,
  Down,
  Left,
  Right,
}

console.log(Direction.Up); // 0
console.log(Direction[0]); // "Up"

The compiled JavaScript contains an immediately invoked function expression that builds the bidirectional object:

var Direction;
(function (Direction) {
  Direction[Direction["Up"] = 0] = "Up";
  Direction[Direction["Down"] = 1] = "Down";
  Direction[Direction["Left"] = 2] = "Left";
  Direction[Direction["Right"] = 3] = "Right";
})(Direction || (Direction = {}));

This flexibility comes with a larger bundle footprint. The generated code uses more bytes than a simple object literal. Most applications never use reverse mapping, making the extra code pure overhead.

Union types with as const provide the same compile-time type safety as enums without the reverse mapping machinery. The object literal approach generates minimal JavaScript and works identically across all compilers. The TypeScript 5.0 release notes mention that the verbatimModuleSyntax option makes module semantics predictable, and union types fit that predictability better than enums with their special compilation rules.

Plain const objects sacrifice type safety for simplicity. They work when the codebase treats the values as documentation rather than constraints. API response status codes often fall into this category because external services return arbitrary numbers anyway.

The migration path depends on the enum's role in the codebase. Enums used as discriminated union tags need full type safety and should become union types. Enums used as named constants can become plain objects. Enums with reverse mapping lookups should stay as regular enums.

What to Do With Existing Const Enum Code

Migrating a codebase with existing const enums requires assessing impact before changing code. The first step identifies where const enums appear and whether they cross module boundaries.

migration decision flowchart for const enum replacement strategy

Search the codebase for const enum declarations and catalog their locations. Distinguish between application-internal enums and enums exported from library packages. Internal enums can migrate gradually. Exported enums require immediate attention because downstream consumers may already be hitting compilation failures.

For libraries, the migration path is strict. Remove all const enums from published declaration files. The TypeScript documentation on const enums explains that const enums in .d.ts files create "subtle implications" and "pitfalls" for consumers. The practical implication is that consumers cannot use isolatedModules if they import your const enums.

The migration steps for a library:

Replace const enum declarations with union types using as const
Export both the const object and the extracted type
Update internal code to use the new types
Bump the major version because the change breaks consumers who directly accessed enum values
Document the migration in the changelog

Application code has more flexibility. The preserveConstEnums compiler option provides a temporary bridge. When enabled, the compiler emits runtime objects for const enums instead of removing them entirely. This makes the code compatible with isolated module compilation while preserving the const enum syntax:

// tsconfig.json
{
  "compilerOptions": {
    "preserveConstEnums": true
  }
}

The output JavaScript now includes the enum object:

const Direction = {
  Up: 0,
  Down: 1,
  Left: 2,
  Right: 3,
};

The const enum keyword becomes equivalent to a regular enum in terms of output, but the TypeScript compiler still inlines references during type checking. This creates an inconsistency where development builds inline values but production builds use the runtime object.

The better approach for application code migrates const enums to union types one module at a time. Start with modules that interact with external dependencies or appear in the critical path. These modules cause the most visible failures when const enums break.

The migration preserves type safety by using the union type extraction pattern. Tests catch any mismatches where code passed invalid values that const enums silently accepted. Strict TypeScript configurations with strict enabled surface these issues immediately.

For large codebases, automated refactoring tools can handle the mechanical transformation. A codemod script searches for const enum declarations, generates the equivalent as const object and type extraction, and updates references throughout the codebase. The TypeScript compiler API provides the parsing and type information needed to build such tools.

The investment in migration pays off in build performance and reliability. Codebases that remove const enums can enable isolatedModules and use faster build tools. The reduction in compilation time often measures in seconds for medium-sized projects and minutes for large monorepos.

Frequently Asked Questions

Can I still use regular enums without the const modifier?

Yes. Regular enums work correctly with isolated module compilation because they emit runtime objects. The TypeScript compiler team deprecated only const enums due to their specific inlining behavior. Regular enums remain a supported feature with no planned deprecation.

Does preserveConstEnums make const enums safe to use?

No. The preserveConstEnums option emits runtime objects but does not solve the version drift problem. If your library ships .d.ts files with const enums, downstream consumers still inline values at compile time based on your declaration file. The runtime object your library includes may have different values, causing the same silent failures const enums are known for.

Why not just ban const enums with a linter rule?

Linter rules prevent new const enums but do not address existing ones or const enums in dependencies. The TypeScript compiler deprecated const enums to signal that the feature causes real problems and the team will not fix edge cases. Migration to alternatives provides a permanent solution rather than piecemeal prevention.

Will regular enums eventually be deprecated too?

The TypeScript team has not announced plans to deprecate regular enums. The TypeScript handbook still documents enums as a standard feature alongside the as const alternative, giving developers a choice based on their needs. Const enums failed because they broke fundamental module system assumptions, not because enums as a concept are flawed.

How do union types handle bitwise operations like flags?

Union types cannot represent computed values in the type itself, so bitwise flag operations work better with plain const objects. Define the base flags as separate properties and combine them at runtime. The type system sees only the defined properties, not the computed combinations. This limitation makes plain objects more practical than union types for permission flags and similar use cases.

The Future of Enums in TypeScript

The TypeScript compiler team's decision to deprecate const enums reflects a broader shift toward compilation models that prioritize speed and simplicity over optimization tricks. Modern JavaScript bundlers and build tools achieve better performance through parallelization and caching than through aggressive inlining. The zero-runtime-cost promise of const enums mattered more when JavaScript environments were slower and every byte counted.

Union types with as const emerged as the recommended pattern because they align with JavaScript's object literals while providing TypeScript's type safety. The pattern requires no special compiler support and works identically whether the code compiles with tsc, esbuild, swc, or any future compiler. Developers can reason about the code's behavior without understanding const enum inlining rules.

Related posts on TypeScript's evolution cover adjacent deprecation decisions. The TypeScript 6 breaking changes guide discusses other features the compiler team phased out for similar reliability reasons. The TypeScript 6 final JavaScript release explains how new ECMAScript proposals influence TypeScript's feature set. The TypeScript decorators legacy to TC39 migration shows another case where TypeScript deprecated an experimental feature in favor of the standardized alternative.

Const enums served their purpose when build pipelines were simpler and projects rarely mixed compilers. The ecosystem has moved on. The migration to union types or const objects removes a source of subtle bugs and makes TypeScript codebases more portable across different build tools. Teams that complete the migration gain faster build times and fewer production surprises. The const enum deprecation pushes TypeScript toward patterns that scale with modern development workflows rather than fighting against them.

TypeScript Function Overloads in 2026: When They Clarify and When They Mislead the Caller

jsmanifest — Thu, 05 Nov 2026 06:05:52 +0000

TypeScript Function Overloads in 2026: When They Clarify and When They Mislead the Caller

Function overloads in TypeScript let developers declare multiple signatures for a single function, each promising a different relationship between inputs and outputs. The feature sounds clean on paper: one function name, multiple valid call patterns, all type-checked. The TypeScript compiler resolves which signature matches at each call site, and developers get precise return types without runtime branching.

The problem surfaces when teams write overloads without understanding the first-match resolution rule documented in the TypeScript handbook. The compiler tests signatures in declaration order and stops at the first compatible match. A later, more specific signature never runs if an earlier, broader one already fits the arguments. The code compiles, callers see the wrong return type, and the confusion spreads through a codebase. Teams add more overloads to fix edge cases, the signature list grows to six or eight entries, and nobody can predict which one will match a given call.

Function overload problem — compiler picks wrong signature

The solution is to recognize when overloads add value and when they obscure intent. Overloads clarify APIs when different argument shapes truly require different return types, a pattern common in DOM APIs and framework entry points. Union types serve better when the function logic treats all inputs uniformly. Understanding resolution order, maintaining signature consistency, and choosing the simpler tool when both work keeps overload sets readable.

Function overload solution — correct signature selection

Key Takeaways

TypeScript resolves overload signatures using first-match logic in declaration order, not by choosing the most specific match.
Overloads clarify APIs when different argument shapes require different return types; union types serve better for uniform handling.
Signature order determines which overload the compiler selects, making consistency and narrow-to-broad ordering critical.
Overload sets exceeding three signatures often signal that a discriminated union or generic constraint would communicate intent more clearly.
The implementation signature must accept all overload cases but remains invisible to callers, creating a maintenance gap when signatures diverge.

How TypeScript Resolves Overload Signatures: First Match Wins

The compiler tests overload signatures in the order developers write them, stopping at the first compatible match. When a function call passes type checking against an overload signature, TypeScript uses that signature's return type and never evaluates later entries. This resolution rule appears in the type compatibility section of the official handbook: "When a function has overloads, each overload in the target type must be matched by a compatible signature on the source type."

function parse(input: string): string;
function parse(input: number): number;
function parse(input: string | number): string | number {
  return typeof input === 'string' ? input.toUpperCase() : input * 2;
}

const result1 = parse('hello'); // type: string
const result2 = parse(42); // type: number

The example above works because the compiler checks parse('hello') against the first signature, finds a match, and assigns the return type string. The second call checks against the second signature first (the string signature does not match a number argument), matches, and returns number. Both callers see precise types.

The failure mode appears when an earlier signature accepts the same arguments as a later one. The compiler matches the broader signature first and never reaches the specific case.

function process(data: string | number): string | number;
function process(data: string): string;
function process(data: string | number): string | number {
  return typeof data === 'string' ? data.toUpperCase() : data * 2;
}

const result = process('test'); // type: string | number (not string)

TypeScript function overload resolution order

The caller passes a string, which satisfies both signatures. The compiler tests the first signature (string | number parameter), matches, and uses its return type (string | number). The second signature never runs. The developer intended process('test') to return string, but the signature order prevents that inference.

The solution places narrow signatures before broad ones. The compiler stops at the first match, so developers must write the most specific cases first.

function process(data: string): string;
function process(data: number): number;
function process(data: string | number): string | number {
  return typeof data === 'string' ? data.toUpperCase() : data * 2;
}

const result = process('test'); // type: string

Reordering the signatures lets the compiler test the string case first, match it, and return the specific type. The union signature sits last as a fallback. The implementation signature at the end must still accept all parameter combinations because the runtime executes only one function body.

When Overloads Clarify Intent: DOM APIs and Multiple Signatures

Overloads improve clarity when a function accepts fundamentally different argument shapes that map to distinct return types. The DOM querySelector method demonstrates this pattern: calling it with a tag name returns a specific element type, while a generic selector returns a more general Element.

function querySelector(selectors: 'div'): HTMLDivElement | null;
function querySelector(selectors: 'span'): HTMLSpanElement | null;
function querySelector(selectors: string): Element | null;
function querySelector(selectors: string): Element | null {
  return document.querySelector(selectors);
}

const div = querySelector('div'); // type: HTMLDivElement | null
const span = querySelector('span'); // type: HTMLSpanElement | null
const generic = querySelector('.class'); // type: Element | null

The function signature communicates three guarantees without conditional types or runtime checks. Callers passing 'div' receive a narrower type than callers using a class selector. The TypeScript compiler enforces this relationship because the first two signatures handle specific string literals, and the third signature catches all other string inputs.

Framework entry points often follow this pattern. A routing library might return different handler types based on the HTTP method.

function route(method: 'GET', path: string): GetHandler;
function route(method: 'POST', path: string): PostHandler;
function route(method: 'PUT', path: string): PutHandler;
function route(method: string, path: string): Handler {
  // implementation
}

Each signature maps a specific method string to its corresponding handler type. Callers see distinct return types without inspecting the implementation. The overload list serves as documentation, showing which methods the function supports.

The value disappears when signatures differ only in optional parameters or when the return type stays constant across all cases. Overloads add noise without improving type inference.

// No benefit — union type works better
function log(message: string, level: 'info'): void;
function log(message: string, level: 'warn'): void;
function log(message: string, level: 'error'): void;
function log(message: string, level: string): void {
  console.log(`[${level}] ${message}`);
}

// Simpler with union
function log(message: string, level: 'info' | 'warn' | 'error'): void {
  console.log(`[${level}] ${message}`);
}

The overload version requires four signature declarations to express what a union type handles in one line. The return type stays void in every case, so the extra signatures provide no inference benefit. Developers reading the code must parse multiple lines to understand a simple constraint.

When Overloads Mislead: Order Matters and Hidden Complexity

Overload order creates a maintenance trap when teams add new signatures without auditing existing ones. A function starts with two overloads, a third case appears months later, and the developer appends it at the end. The compiler matches an earlier signature first, and the new case never runs.

Consider a validation function that evolved over several iterations:

// Original design
function validate(input: string): boolean;
function validate(input: number): boolean;
function validate(input: string | number): boolean {
  return input.toString().length > 0;
}

// Later addition (appended at end)
function validate(input: string): boolean;
function validate(input: number): boolean;
function validate(input: { value: string }): string; // New case
function validate(input: string | number | { value: string }): boolean | string {
  if (typeof input === 'object') return input.value;
  return input.toString().length > 0;
}

The third signature never matches because the compiler stops at the first string or number overload. Callers passing { value: 'test' } see a type error because no signature accepts that shape at the top of the list. The developer must reorder signatures to fix the issue, but the codebase may already rely on the existing order for other call sites.

Signature ordering	Compiler behavior	Caller experience
Narrow types first	Matches specific cases early, fallback types last	Precise inference, predictable resolution
Broad types first	Matches general cases early, specific types unreachable	Imprecise inference, silent fallback
Inconsistent order	Matches depend on declaration sequence	Unpredictable inference, maintenance burden

Overload resolution comparison — narrow vs broad first

The implementation signature compounds the problem. It must accept all parameter combinations from every overload, but callers never see it. Developers change an overload without updating the implementation signature, and the function compiles but crashes at runtime when an edge case hits the unhandled path.

function transform(input: string): string;
function transform(input: number): number;
function transform(input: string | number): string | number {
  // Forgot to handle number case
  return input.toUpperCase(); // Runtime error if input is number
}

The implementation signature promises to accept string | number, but the body only handles strings. TypeScript permits this gap because the implementation signature remains invisible to external callers. The function compiles, runtime tests pass if they only cover string inputs, and the production crash happens when a number arrives.

Overloads vs Union Types: Choosing the Right Tool in 2026

Union types handle cases where the function treats all inputs uniformly. Overloads serve cases where different inputs require different return types. The decision tree appears simple, but teams often default to overloads when union types would deliver clearer intent.

A formatting function demonstrates the distinction:

// Overloads (unnecessary complexity)
function format(value: string, style: 'uppercase'): string;
function format(value: string, style: 'lowercase'): string;
function format(value: string, style: 'capitalize'): string;
function format(value: string, style: string): string {
  switch (style) {
    case 'uppercase': return value.toUpperCase();
    case 'lowercase': return value.toLowerCase();
    case 'capitalize': return value.charAt(0).toUpperCase() + value.slice(1);
    default: return value;
  }
}

// Union type (clearer)
function format(
  value: string,
  style: 'uppercase' | 'lowercase' | 'capitalize'
): string {
  switch (style) {
    case 'uppercase': return value.toUpperCase();
    case 'lowercase': return value.toLowerCase();
    case 'capitalize': return value.charAt(0).toUpperCase() + value.slice(1);
  }
}

The overload version requires four signatures to constrain a single parameter. The return type stays string in every case, so the extra declarations add no type-safety benefit. The union version communicates the same constraint in one signature. Callers see the same autocomplete options, the same type errors for invalid styles, and the implementation stays identical.

TypeScript overloads versus union types decision tree

Overloads add value when the return type changes based on argument shape. A data fetcher that returns different response structures based on the endpoint demonstrates appropriate overload use:

function fetch(endpoint: '/users'): Promise<User[]>;
function fetch(endpoint: '/posts'): Promise<Post[]>;
function fetch(endpoint: '/comments'): Promise<Comment[]>;
function fetch(endpoint: string): Promise<unknown> {
  return globalThis.fetch(endpoint).then(r => r.json());
}

const users = await fetch('/users'); // type: User[]
const posts = await fetch('/posts'); // type: Post[]

Each endpoint returns a distinct type. A union type cannot express this relationship without conditional types or discriminated unions, both of which push complexity into the type system. Overloads keep the signature list flat and readable.

Scenario	Union types	Overloads	Recommended approach
Same return type, constrained parameter	Single signature, clear constraint	Multiple signatures, repeated return type	Union types
Different return types per argument	Requires conditional types or generics	Natural signature mapping	Overloads
Optional parameters only	Single signature with optional markers	Multiple signatures with incremental parameters	Union types
Runtime behavior varies by type	Union parameter, type guards in body	Overload signature, type narrowing at call site	Depends on call-site complexity

Overload vs union type decision flow

The choice impacts maintainability. Overload sets grow as new cases appear, while union types extend by adding another member to the union. A function with six overloads becomes harder to audit than a union with six members because developers must verify signature order and consistency across all entries.

Production Patterns: Writing Maintainable Overload Sets

Maintainable overload sets follow three rules: narrow signatures precede broad ones, the implementation signature accepts all cases, and the total signature count stays below four. When a function exceeds four overloads, the signature list obscures intent more than it clarifies.

The signature ordering rule addresses first-match resolution. The compiler stops at the first compatible signature, so the most specific cases must appear first.

// Correct ordering
function process(input: 'start'): StartResult;
function process(input: 'stop'): StopResult;
function process(input: string): GeneralResult;
function process(input: string): StartResult | StopResult | GeneralResult {
  if (input === 'start') return { type: 'start', timestamp: Date.now() };
  if (input === 'stop') return { type: 'stop', timestamp: Date.now() };
  return { type: 'general', value: input };
}

String literal types appear before the string union. The compiler checks 'start' and 'stop' before falling back to the general case. Callers passing specific literals see narrow return types. Callers passing other strings see the general type.

Overload signature resolution with narrow-to-broad ordering

The implementation signature must handle all parameter combinations from every overload. Mismatches between overload signatures and the implementation create runtime gaps.

// Dangerous — implementation does not cover all overloads
function transform(input: string): string;
function transform(input: number): number;
function transform(input: boolean): boolean; // Added later
function transform(input: string | number): string | number {
  // Missing boolean case
  if (typeof input === 'string') return input.toUpperCase();
  return input * 2;
}

The third overload promises to accept boolean inputs, but the implementation signature excludes them. TypeScript permits this because the implementation signature stays internal. The function compiles, and the boolean case crashes at runtime. Teams prevent this gap by ensuring the implementation signature always union-matches all overload parameters.

Signature count matters. Three overloads communicate distinct cases without overwhelming readers. Six overloads demand a refactor into discriminated unions or mapped types.

// Too many overloads (hard to maintain)
function request(method: 'GET', url: string): Promise<string>;
function request(method: 'POST', url: string, body: string): Promise<string>;
function request(method: 'PUT', url: string, body: string): Promise<string>;
function request(method: 'DELETE', url: string): Promise<string>;
function request(method: 'PATCH', url: string, body: string): Promise<string>;
function request(method: 'HEAD', url: string): Promise<void>;
function request(method: string, url: string, body?: string): Promise<string | void> {
  // implementation
}

// Better with discriminated union
type RequestConfig =
  | { method: 'GET' | 'DELETE' | 'HEAD'; url: string }
  | { method: 'POST' | 'PUT' | 'PATCH'; url: string; body: string };

function request(config: RequestConfig): Promise<string | void> {
  // implementation
}

The discriminated union collapses six signatures into two union members. Callers construct objects instead of passing positional arguments, but the type system enforces the same constraints. The function signature stays flat, and adding new methods requires extending the union instead of appending another overload.

Common Mistakes: Inconsistent Return Types and Unreachable Signatures

Return type inconsistency appears when developers add overloads without coordinating the implementation. The overload signatures promise one type, the implementation returns another, and TypeScript accepts the mismatch because the implementation signature remains invisible.

function parse(input: string): number;
function parse(input: number): string;
function parse(input: string | number): string | number {
  // Implementation returns wrong type for string input
  if (typeof input === 'string') return input; // Should return number
  return input.toString(); // Should return string
}

const result1 = parse('123'); // type: number, runtime: string
const result2 = parse(123); // type: string, runtime: string

The first overload promises string input returns number, but the implementation returns the string unchanged. TypeScript infers the return type as number based on the overload signature, but the runtime value stays a string. Operations expecting a number crash when the string arrives. The noImplicitReturns compiler option catches missing return statements but not type mismatches between overload promises and implementation behavior.

Unreachable signatures appear when a broad signature precedes a narrow one. The compiler matches the broad case first and never evaluates later entries.

// Second signature unreachable
function handle(input: unknown): string;
function handle(input: string): string; // Never matches
function handle(input: unknown): string {
  return typeof input === 'string' ? input : String(input);
}

const result = handle('test'); // Uses first signature (unknown parameter)

The first signature accepts unknown, which matches any argument including string. The compiler stops there and never checks the second signature. Callers passing strings see the first signature's return type, which happens to match the second signature in this example but obscures the intended narrow match. Linters do not flag unreachable signatures because the function remains type-safe, the issue surfaces as unexpected inference behavior rather than a compile error.

The fix reorders signatures or removes redundant ones. When signatures overlap, the narrow case must appear first. When signatures provide no additional inference benefit, removing them clarifies intent.

// Corrected ordering
function handle(input: string): string;
function handle(input: unknown): string;
function handle(input: unknown): string {
  return typeof input === 'string' ? input : String(input);
}

const result = handle('test'); // Uses first signature (string parameter)

Redundant overloads appear when developers add signatures that provide no additional type information. A function with three overloads that differ only in parameter names wastes declaration space.

// Redundant overloads
function calculate(a: number, b: number): number;
function calculate(x: number, y: number): number;
function calculate(first: number, second: number): number;
function calculate(a: number, b: number): number {
  return a + b;
}

Parameter names do not affect type checking. All three signatures accept two numbers and return a number. The extra declarations add no value. A single signature communicates the same constraint.

Frequently Asked Questions

When should a function use overloads instead of union types?

Use overloads when different argument shapes map to different return types and the function cannot express that relationship through a single union type. DOM APIs like querySelector demonstrate this pattern: passing a specific tag name returns a narrow element type, while a generic selector returns Element. Union types serve better when the return type stays constant across all argument combinations or when the function handles all inputs uniformly. Overload sets exceeding three signatures usually signal that a discriminated union or conditional type would communicate the design more clearly.

Does TypeScript choose the most specific overload signature or the first match?

TypeScript uses first-match resolution as documented in the type compatibility handbook. The compiler tests overload signatures in declaration order and stops at the first compatible match. A more specific signature later in the list never runs if an earlier, broader signature already accepts the arguments. This behavior requires developers to order signatures from narrow to broad, placing specific cases before general fallbacks. Signature ordering determines which return type callers see, making declaration sequence a critical part of overload design.

Why does the implementation signature stay invisible to callers?

The implementation signature defines the function body's parameter and return types but does not participate in call-site type checking. TypeScript uses only the overload signatures to infer types at call sites. This separation lets developers write a general implementation that handles all cases while exposing specific signatures to callers. The gap creates a maintenance risk: overload signatures can promise types the implementation does not deliver, and TypeScript accepts the mismatch because the implementation signature remains internal. Teams address this by ensuring the implementation signature accepts a union of all overload parameters and returns a union of all overload return types.

Can overload signatures have different parameter counts?

Yes, overload signatures can vary parameter counts to model functions with optional behavior based on argument presence. The implementation signature must accept all possible parameter combinations, typically by marking later parameters optional or using rest parameters. The compiler matches the first signature where all required parameters fit the call arguments. This pattern works for functions like event handlers where passing additional context arguments changes behavior, but it requires careful ordering to prevent broader signatures from shadowing narrower ones.

What compiler options affect overload behavior?

The strictBindCallApply option enables precise type checking for call, bind, and apply methods on overloaded functions, ensuring arguments match the selected signature. The noImplicitReturns option catches missing return statements in the implementation but does not verify that return types match overload promises. No compiler option currently warns about unreachable overload signatures or inconsistent return types between overloads and implementation. Teams rely on code review and testing to catch those gaps.

Conclusion

Function overloads in TypeScript clarify APIs when different argument shapes require different return types, but first-match resolution and order dependency create maintainability traps that grow with signature count. Narrow signatures must precede broad ones to prevent the compiler from stopping at an imprecise match. Union types deliver better outcomes when the return type stays constant or when the function handles all inputs uniformly. Keeping overload sets below four signatures, ensuring the implementation signature accepts all cases, and auditing signature order during code review prevent the confusion that emerges when developers add new cases without understanding resolution rules. Teams that recognize when overloads add value and when they obscure intent build APIs that communicate constraints through types rather than documentation.

TypeScript `globalThis` Typing in 2026: Safely Adding Properties to the Global Scope Without `any`

jsmanifest — Wed, 04 Nov 2026 06:06:57 +0000

TypeScript `globalThis` Typing in 2026: Safely Adding Properties to the Global Scope Without `any`

Why globalThis Typing Still Matters in 2026

The global scope remains the path of least resistance for quick hacks. Developers drop variables onto globalThis to share state across modules, expose debug hooks to the browser console, or bridge third-party scripts that expect global names. TypeScript sees these assignments and defaults to any, erasing type safety at the exact boundary where typos and runtime crashes cluster.

The broken pattern looks innocent: globalThis.featureFlags = { darkMode: true } compiles without complaint, but every access to globalThis.featureFlags surrenders type checking. When another engineer misspells darkMode as darkmode three modules away, the compiler stays silent and the test suite passes until production traffic hits the undefined code path.

Declaration merging solves this. TypeScript permits extending the globalThis interface with new properties, restoring autocomplete and type errors for every global access. The corrected pattern uses an ambient declaration to teach the compiler about the new global without changing runtime behavior.

This pattern matters when a codebase has already committed to global state and rewriting it would delay shipping features. The technique also bridges legacy constraints: third-party analytics scripts, browser extensions that inject globals, or Node.js test runners that expose assertion libraries on global. Knowing when each variant (globalThis, window, global) breaks prevents silent failures in cross-environment builds.

Key Takeaways

TypeScript allows extending the globalThis interface via declaration merging, restoring full type safety for global properties without runtime overhead.
The declare global block works only in module files; script files can declare directly on interface globalThis but lose module isolation.
The window, global, and globalThis identifiers reference different objects depending on the runtime environment, causing subtle breakage when the wrong one is typed.
Proper cleanup between test suites requires explicit delete statements, as TypeScript type declarations do not remove runtime properties.
Most use cases have better alternatives: environment variable objects, dependency injection, or module-scoped constants avoid global namespace pollution entirely.

The Problem: Adding Properties to globalThis Without any

A common scenario surfaces when integrating analytics libraries. The vendor provides a snippet that assigns a tracker instance to the global scope:

globalThis.analytics = {
  track: (event, properties) => {
    // implementation
  },
  identify: (userId, traits) => {
    // implementation
  }
};

TypeScript infers the type of globalThis.analytics as any because globalThis is a predefined global with a fixed type that does not include an analytics property. Every subsequent access to globalThis.analytics.track bypasses type checking. The engineer who writes globalThis.analytics.trak("click") will not receive an error until runtime.

TypeScript globalThis without proper typing

Attempting to add a type annotation at the assignment site fails:

globalThis.analytics = {
  track: (event: string, properties: Record<string, unknown>) => {},
  identify: (userId: string, traits: Record<string, unknown>) => {}
} as AnalyticsClient;
// Error: Property 'analytics' does not exist on type 'typeof globalThis'

The error reveals the core issue: TypeScript has a preexisting interface definition for globalThis that does not include an analytics member. Adding the property at runtime does not change the compile-time type.

The compiler blocks the assignment because it cannot verify that adding arbitrary properties to a global object is safe. The solution requires teaching TypeScript about the new property through declaration merging.

Declaration Merging: The Official TypeScript Pattern

Declaration merging extends an existing interface by declaring it again with additional members. TypeScript combines all declarations of the same interface into a single definition. For globalThis, this means adding a new interface declaration that specifies the custom property:

// types/global.d.ts
declare global {
  interface globalThis {
    analytics: {
      track: (event: string, properties: Record<string, unknown>) => void;
      identify: (userId: string, traits: Record<string, unknown>) => void;
    };
  }
}

export {};

The declare global block is necessary when the file is a module (contains an import or export statement). The empty export {} at the end forces TypeScript to treat the file as a module, which activates the declare global requirement. Without this, the declaration would apply to the module's local scope instead of the global scope.

After adding this declaration, the original assignment compiles without error:

globalThis.analytics = {
  track: (event, properties) => {
    console.log(event, properties);
  },
  identify: (userId, traits) => {
    console.log(userId, traits);
  }
};

Type checking now works across the entire codebase. Accessing globalThis.analytics.track provides autocomplete for the method signature, and misspelling the method name triggers a compile error:

// Autocomplete suggests: track, identify
globalThis.analytics.track("pageview", { path: "/home" });

// Error: Property 'trak' does not exist on type
globalThis.analytics.trak("click");

The declaration can reference custom types for cleaner definitions:

// types/global.d.ts
interface AnalyticsClient {
  track: (event: string, properties: Record<string, unknown>) => void;
  identify: (userId: string, traits: Record<string, unknown>) => void;
}

declare global {
  interface globalThis {
    analytics: AnalyticsClient;
  }
}

export {};

This pattern works for any property type. Complex nested objects, function signatures, and generic constraints all merge correctly. The TypeScript compiler released version 3.4 with explicit support for typing globalThis, as documented in the TypeScript 3.4 release notes.

globalThis vs window vs global: When Each Pattern Breaks

The JavaScript language provides three identifiers for the global object: globalThis, window, and global. Each identifier works in specific environments, and typing the wrong one causes silent failures.

Identifier	Browser	Node.js	Web Worker	When it breaks
`globalThis`	✓	✓	✓	Never (ES2020+)
`window`	✓	✗	✗	Node.js and Worker environments throw ReferenceError
`global`	✗	✓	✗	Browser and Worker environments have no `global`

Typing window creates code that compiles for browser targets but crashes in Node.js:

// types/global.d.ts
declare global {
  interface Window {
    analytics: AnalyticsClient;
  }
}

export {};

// runtime.ts
window.analytics = { /* ... */ };
// ReferenceError: window is not defined (in Node.js)

The same issue occurs when typing global for Node.js projects that later run in a browser:

// types/global.d.ts
declare global {
  namespace NodeJS {
    interface Global {
      analytics: AnalyticsClient;
    }
  }
}

export {};

// runtime.ts
global.analytics = { /* ... */ };
// ReferenceError: global is not defined (in browser)

The globalThis identifier solves this. Introduced in ES2020, globalThis references the global object in all environments. Browsers alias it to window, Node.js aliases it to global, and Web Workers provide it directly. Code that uses globalThis runs unchanged across all targets.

TypeScript's type definitions for globalThis live in lib.es2020.d.ts. Projects targeting ES2020 or later automatically include these definitions. For older targets, developers must add "lib": ["ES2020"] to tsconfig.json or include a polyfill that backfills the globalThis identifier at runtime.

Module vs Script Context: Why declare global Sometimes Fails

TypeScript distinguishes between module files and script files based on the presence of import or export statements. This distinction changes how global declarations work.

A script file has no import or export statements. Its declarations apply to the global scope by default:

// types/global.d.ts (script file)
interface globalThis {
  analytics: AnalyticsClient;
}

This works without the declare global wrapper. TypeScript merges the interface directly into the global globalThis type. However, the file lacks module isolation. Any types defined here pollute the global namespace and can conflict with types in other files.

A module file contains at least one import or export statement. Module files have their own scope, so declarations do not affect the global scope unless wrapped in declare global:

// types/global.d.ts (module file)
export {};

interface globalThis {
  analytics: AnalyticsClient;
}
// This declaration applies to the module scope, not the global scope

The globalThis interface above creates a local type that shadows the global globalThis. Accessing globalThis.analytics in another file still returns any because the global type has not changed.

The correct pattern for a module file uses declare global:

// types/global.d.ts (module file)
declare global {
  interface globalThis {
    analytics: AnalyticsClient;
  }
}

export {};

The export {} forces the file to be a module while exporting nothing. This preserves module isolation while allowing the declare global block to modify the global scope.

Projects that use ES modules (.mts extension or "type": "module" in package.json) default to module context. Adding a global type declaration to such a project without declare global produces no effect, and the compiler offers no warning about the mistake.

Real-World Patterns: Environment Variables, Feature Flags, and Runtime Config

Three scenarios drive most globalThis typing: environment variables exposed by bundlers, feature flags controlled by remote config, and runtime configuration injected by server-side rendering.

Environment Variables

Bundlers like Vite expose environment variables through import.meta.env. TypeScript does not know which variables the bundler will inject, so accessing import.meta.env.VITE_API_URL returns string | undefined. Declaring the variables restores specificity:

// env.d.ts
interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_ENABLE_ANALYTICS: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

This pattern extends ImportMeta instead of globalThis, but the principle is identical. The declaration merges into the existing interface, and all accesses to import.meta.env gain type safety.

Some projects assign environment variables directly to globalThis for access in non-module code:

// runtime-env.ts
declare global {
  interface globalThis {
    ENV: {
      API_URL: string;
      ENABLE_ANALYTICS: boolean;
    };
  }
}

globalThis.ENV = {
  API_URL: import.meta.env.VITE_API_URL,
  ENABLE_ANALYTICS: import.meta.env.VITE_ENABLE_ANALYTICS === "true"
};

export {};

This approach centralizes the boolean parsing logic and provides a single typed object for environment configuration.

Feature Flags

Remote configuration services deliver feature flags as JSON. The consuming application receives an object with boolean properties:

// feature-flags.d.ts
declare global {
  interface globalThis {
    featureFlags: {
      enableDarkMode: boolean;
      enableBetaFeatures: boolean;
      maxUploadSizeMB: number;
    };
  }
}

export {};

// init.ts
fetch("/api/feature-flags")
  .then(res => res.json())
  .then(flags => {
    globalThis.featureFlags = flags;
  });

Components that check flags receive autocomplete and type errors:

if (globalThis.featureFlags.enableDarkMode) {
  document.body.classList.add("dark");
}

// Error: Property 'enableDrakMode' does not exist
if (globalThis.featureFlags.enableDrakMode) {
  // typo caught at compile time
}

The risk here is runtime shape mismatch. If the API response changes and removes enableDarkMode, the application will read undefined at runtime despite the TypeScript type claiming a boolean. Adding runtime validation with a library like Zod or writing a manual assertion function mitigates this.

TypeScript globalThis feature flags pattern

Server-Side Rendering Config

Frameworks like Next.js inject configuration into the initial HTML payload. The server renders a `tag that assigns towindow`:

`html

window.INITIAL_STATE = {
user: { id: "123", name: "Alice" },
cart: []
};

The client-side code reads this state before making API calls:

`typescript
// initial-state.d.ts
declare global {
interface Window {
INITIAL_STATE: {
user: { id: string; name: string };
cart: Array<{ productId: string; quantity: number }>;
};
}
}

export {};
`

`typescript // hydrate.ts const initialState = window.__INITIAL_STATE__; renderApp(initialState); `

This pattern works only in browser environments. Server-side code that references window.__INITIAL_STATE__ will crash. Conditional checks guard the access:

`typescript const state = typeof window !== "undefined" ? window.__INITIAL_STATE__ : getDefaultState(); `

The type system does not enforce this check. Developers must remember to add it, or the build will succeed and production will fail when server-side rendering tries to reference window.

Testing and Cleanup: Avoiding Pollution Between Test Suites

Global state persists across test files when a test runner executes all files in a single process. A test that assigns globalThis.featureFlags = { enableBeta: true } leaves that property set for subsequent tests. The next test suite that checks if (globalThis.featureFlags.enableBeta) will read the previous value instead of the expected undefined, causing false passes or failures.

The TypeScript declaration does not remove runtime properties. Deleting the type does not reset the global:

`typescript // This does not work: declare global { interface globalThis { featureFlags: undefined; // only affects compile-time type } } `

Proper cleanup requires explicit delete statements in an afterEach hook:

`typescript // test-setup.ts afterEach(() => { delete globalThis.featureFlags; delete globalThis.analytics; delete globalThis.ENV; }); `

TypeScript will still report errors if code accesses the deleted property, because the type declaration remains in scope. Wrapping the delete in a type guard silences this:

`typescript afterEach(() => { if ("featureFlags" in globalThis) { delete globalThis.featureFlags; } }); `

Alternatively, setting the property to undefined instead of deleting it preserves the type shape:

`typescript afterEach(() => { globalThis.featureFlags = undefined as any; }); `

This approach requires changing the type declaration to allow undefined:

`typescript declare global { interface globalThis { featureFlags?: { enableDarkMode: boolean; enableBetaFeatures: boolean; }; } } `

Now every access requires an optional chain or existence check:

`typescript if (globalThis.featureFlags?.enableDarkMode) { // safe access } `

The choice between deletion and undefined depends on whether the codebase prefers explicit existence checks or assumes the property is always present during normal operation.

When NOT to Use globalThis: Better Alternatives for Most Use Cases

Typing globalThis addresses a tactical problem but does not solve the strategic issue of global state. Most applications benefit from alternatives that avoid polluting the global namespace.

Module-Scoped Constants

Configuration that never changes at runtime belongs in a module:

`typescript // config.ts export const config = { apiUrl: import.meta.env.VITE_API_URL, enableAnalytics: import.meta.env.VITE_ENABLE_ANALYTICS === "true" }; `

This provides the same centralized access without touching globalThis. TypeScript infers the exact types, and tree shaking can remove unused properties in production builds. For more patterns around modern TypeScript library configuration, see Create a Modern TypeScript/JavaScript Library for 2023.

Dependency Injection

Services like analytics clients belong in dependency containers:

`typescript
// services.ts
export class Analytics {
track(event: string, properties: Record): void {
// implementation
}
}

export const analytics = new Analytics();
`

`typescript
// component.ts
import { analytics } from "./services";

analytics.track("pageview", { path: "/home" });
`

This supports testing through mock injection and avoids singleton globals. The pattern scales to complex applications without namespace conflicts.

Context Objects

React, Vue, and other frameworks provide context mechanisms for shared state:

`typescript
// feature-flags-context.tsx
const FeatureFlagsContext = createContext({
enableDarkMode: false,
enableBetaFeatures: false
});

export function FeatureFlagsProvider({ children }) {
const [flags, setFlags] = useState(defaultFlags);

useEffect(() => {
fetch("/api/feature-flags")
.then(res => res.json())
.then(setFlags);
}, []);

return (

{children}

);
}

export const useFeatureFlags = () => useContext(FeatureFlagsContext);
`

Components consume flags through the hook, and the framework handles the scoping. This eliminates global pollution and simplifies testing by allowing test wrappers to provide mock values.

When globalThis Is Actually Correct

The pattern remains valid for:

Integrating third-party scripts that expect global names (analytics vendors, error trackers)
Exposing debug utilities to the browser console during development
Bridging module code and legacy non-module scripts in a migration period
Polyfilling missing global APIs in older environments

If the global property ships to production, the declaration should include comments explaining why alternatives were rejected:

`typescript declare global { interface globalThis { /** * Segment analytics instance. * Global assignment required by vendor SDK. * See: https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/ */ analytics: SegmentAnalytics; } } `

This prevents future engineers from assuming the global was added carelessly. For guidance on structuring cross-cutting concerns like correlation IDs in distributed systems, see Correlation IDs in AI Agent Architectures.

Frequently Asked Questions

Can I declare multiple properties on globalThis in separate files?

Yes. TypeScript merges all declarations of the same interface across files. Each file can extend globalThis with different properties, and the compiler combines them into a single type. This works as long as the properties do not conflict.

Why does my globalThis declaration not work in a .ts file?

The file likely has no import or export statements, making it a script instead of a module. Script files cannot use declare global. Add export {} to force module context, or move the declaration to a .d.ts file.

How do I prevent accidental writes to typed global properties?

Use readonly in the declaration:

`typescript declare global { interface globalThis { readonly featureFlags: { enableDarkMode: boolean; }; } } `

This prevents assignment after initialization:

`typescript globalThis.featureFlags = newFlags; // Error: Cannot assign to 'featureFlags' `

Does globalThis typing work with strictNullChecks enabled?

Yes. The compiler enforces nullability based on the declared type. If the declaration does not include undefined, TypeScript assumes the property is always present. If runtime code might delete the property, add ? to the declaration or union with undefined.

What happens if two libraries declare the same global property with different types?

TypeScript reports an error when merging incompatible types. If library A declares globalThis.config: { timeout: number } and library B declares globalThis.config: { retries: number }, the compiler cannot merge them. The developer must declare a combined type that satisfies both libraries or file a bug with the library maintainers.

Conclusion

Declaration merging makes globalThis properties type-safe without runtime cost. The pattern works across all environments when using globalThis instead of window or global, and it integrates with existing toolchains without configuration changes. The technique fills a narrow gap: code that already relies on global state and cannot migrate to module-scoped alternatives.

Most new code should avoid globalThis entirely. Module exports, dependency injection, and framework context APIs provide better isolation and testability. When globals are unavoidable, proper TypeScript declarations prevent the most common failure mode: silent any types that surrender error checking at the exact boundary where runtime bugs cluster. For broader context on modern TypeScript tooling ecosystems, see Biome vs oxlint Comparison 2026.

TypeScript `@throws` JSDoc and Error Typing in 2026: Why Exceptions Are Still Untyped and What to Do About It

jsmanifest — Tue, 03 Nov 2026 06:06:13 +0000

TypeScript `@throws` JSDoc and Error Typing in 2026: Why Exceptions Are Still Untyped and What to Do About It

Developers write try/catch blocks around TypeScript functions without knowing what exceptions those functions throw. The compiler stays silent when a function that throws NetworkError gets called without a handler, and the codebase ships with runtime crashes that static analysis should have caught. This happens because TypeScript treats exceptions as invisible to the type system.

Problem flow showing unhandled exception propagation in TypeScript

Languages with checked exceptions force developers to declare and handle throws behavior at compile time. TypeScript documentation includes a @throws JSDoc tag, but the tag has no enforcement mechanism. Engineers who write @throws {NetworkError} above a function signature get zero compiler feedback when callers ignore that annotation. The gap between documentation and verification creates a dangerous false confidence.

Solution flow showing explicit Result type error handling

Teams that need predictable error handling in TypeScript codebases must build their own type-safe patterns. Result types, discriminated unions, and explicit error boundaries provide the guarantees the language does not. The solutions require more code than a hypothetical throws keyword, but they work today without waiting for a language feature that may never arrive.

Key Takeaways

TypeScript does not type exceptions and likely never will due to JavaScript runtime semantics and the unchecked exception model.
The @throws JSDoc tag documents throw behavior but provides zero compiler enforcement or type safety.
Result types (Result<T, E>) and discriminated unions create verifiable error handling without language-level throw types.
Error discrimination patterns using instanceof and type guards allow safe exception handling in catch blocks when exceptions remain the chosen approach.
Teams must choose between exceptions with manual documentation (faster to write, harder to verify) and Result types (more verbose, compiler-verified).

Why TypeScript Still Doesn't Type Exceptions in 2026

TypeScript inherits JavaScript's unchecked exception model. Any function can throw any value at any time, and the runtime provides no compile-time guarantees about what gets thrown. Java and C# have checked exceptions where the compiler enforces throw declarations, but JavaScript does not, and TypeScript follows JavaScript semantics.

The language could theoretically add throw types as an optional static analysis layer. TypeScript already diverges from JavaScript in ways that require compilation (enums, namespaces before TypeScript 5.8's --erasableSyntaxOnly). Adding a throws keyword or enforcing @throws annotations would fit that pattern. The TypeScript team has chosen not to pursue this feature.

Three technical barriers prevent practical implementation of throw types in TypeScript:

Dynamic function references lose throw information under indirection. When a function gets assigned to a variable, passed as a callback, or returned from another function, TypeScript would need to preserve throw signatures through every layer of indirection. Higher-order functions and async operations create combinatorial explosion in the number of possible throw paths.

Third-party code has no throw annotations. The vast majority of npm packages ship without throw documentation. Even if TypeScript added throw types tomorrow, existing libraries would appear to throw nothing. The type system would require every developer to manually annotate every dependency, or accept a mass of implicit any exceptions that defeat the entire purpose.

JavaScript's throw accepts any type. Code can throw strings, numbers, null, or custom objects. A robust throw type system would need to model all possible thrown values, including edge cases where throw appears in expression position. The complexity of accurately representing JavaScript's throw semantics exceeds the benefit.

TypeScript 5.2 added decorator metadata (accessed via Symbol.metadata) that frameworks use to attach runtime information to classes. Decorator metadata does not extend to function throw signatures. TypeScript 5.8 introduced --erasableSyntaxOnly to restrict syntax to patterns that Node.js type-stripping can handle, but this targets import/export semantics and namespace elimination, not exception typing.

The official TypeScript handbook documents @throws in JSDoc but provides no mechanism to verify those annotations. The tag exists for human readers and documentation generators, not for the compiler.

The @throws JSDoc Tag: What It Provides and What It Doesn't

TypeScript recognizes the @throws JSDoc tag as valid documentation syntax. Developers write @throws {ErrorType} description above function declarations to document exception behavior. IDEs display this information in hover tooltips and generated documentation sites parse it. The compiler ignores it completely during type checking.

/**
 * Fetches user data from the API
 * @throws {NetworkError} when the request fails
 * @throws {ValidationError} when the response is invalid
 */
function fetchUser(id: string): Promise<User> {
  // implementation
}

// This compiles without error despite missing try/catch
const user = await fetchUser("123");

The function signature carries throw information in JSDoc but the call site receives no type error. Developers who read the hover tooltip see the documented exceptions. Developers who skip the tooltip get no warning when they omit error handling. The pattern depends on discipline rather than verification.

JSDoc comments provide value for human communication. A well-documented codebase with consistent @throws annotations helps engineers understand error paths when reading code. Documentation generation tools like TypeDoc extract @throws tags into reference pages. These benefits matter for large teams maintaining complex systems.

The disconnect between documentation and enforcement creates a specific problem: stale annotations. When a function's throw behavior changes but the JSDoc comment does not get updated, the compiler never reports the mismatch. Callers continue seeing outdated throw documentation. Tests might catch the divergence if they cover error paths, but the type system provides no safety net.

TypeScript error handling documentation approaches

Some teams treat @throws annotations as required parts of their style guide and enforce them via linter rules. The eslint-plugin-jsdoc package includes a require-throws rule that demands JSDoc throw documentation on functions that contain throw statements. This catches missing documentation but does not verify that callers handle the documented exceptions.

The pattern works for teams that value documentation completeness and accept that verification happens during code review rather than compilation. For teams that need compiler-enforced error handling, different patterns become necessary.

Building Type-Safe Error Handling Without Language Support

Result types encode success and failure cases directly in return values. A function that can fail returns Result<T, E> where T represents success and E represents failure. Callers must explicitly unwrap the result to access the success value, forcing them to handle the error case.

type Result<T, E> = 
  | { ok: true; value: T }
  | { ok: false; error: E };

function parseConfig(data: unknown): Result<Config, ConfigError> {
  if (!isValidConfig(data)) {
    return { ok: false, error: new ConfigError("Invalid structure") };
  }
  return { ok: true, value: data as Config };
}

const result = parseConfig(rawData);
if (!result.ok) {
  // Compiler requires handling the error case before accessing value
  console.error(result.error);
  return;
}
// result.value is now safely typed as Config
processConfig(result.value);

The type system enforces error handling at compile time. Attempting to access result.value without checking result.ok produces a type error. The pattern eliminates silent failure propagation because every result must be explicitly unwrapped.

Rust and Go popularized this pattern in systems programming. The Rust standard library uses Result<T, E> as its primary error handling mechanism. Go functions commonly return (value, error) tuples. These languages prove that explicit result types scale to large production systems.

TypeScript libraries provide pre-built Result type implementations. The neverthrow package offers a chainable Result API with .map(), .mapErr(), and .andThen() methods for composing operations. The ts-results package provides similar functionality with a focus on zero-dependency size. Teams can adopt these libraries or implement their own Result type based on their needs.

import { Result, ok, err } from 'neverthrow';

async function fetchUserData(id: string): Promise<Result<User, NetworkError>> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) {
      return err(new NetworkError(response.status));
    }
    const data = await response.json();
    return ok(data);
  } catch (e) {
    return err(new NetworkError(0, 'Connection failed'));
  }
}

// Chaining with automatic error propagation
const result = await fetchUserData('123')
  .andThen(user => validateUser(user))
  .andThen(user => enrichUserData(user));

if (result.isErr()) {
  handleError(result.error);
} else {
  processUser(result.value);
}

Result types add verbosity compared to exceptions. Every fallible operation returns a Result that must be unwrapped. Chaining multiple operations requires .andThen() calls or manual result checking. For teams working in exception-heavy codebases, converting to Result types represents a significant architectural shift.

The tradeoff favors type safety over brevity. Exception-based code can appear cleaner because errors propagate implicitly, but that implicit propagation creates the exact problem Result types solve. When error handling matters more than code conciseness, Result types deliver compiler-verified correctness.

Result Types vs Exceptions: The Practical Trade-Offs

Aspect	Result Types	Exceptions
Compile-time verification	Required by type system	Documentation only
Error propagation	Explicit at every call	Implicit through call stack
Refactoring safety	Compiler catches all call sites	Manual search required
Code volume	Higher (wrapping overhead)	Lower (implicit propagation)
Integration with existing code	Requires conversion layer	Works immediately
Performance overhead	Negligible (return value)	Negligible (modern VMs)
Team learning curve	Moderate (new pattern)	Minimal (familiar)

Result types force every error case to surface at the call site. When a function changes its error type from ConfigError to ConfigError | NetworkError, the compiler reports an error at every location that unwraps the result. This property makes large refactors safer because the type system identifies every affected call site automatically.

Exceptions propagate through intermediate callers without modification. A function that calls another function that might throw does not need to declare or handle the exception. The call stack unwinds until a catch block appears. This behavior reduces code volume because intermediate functions need no error-handling logic, but it also means errors can travel far from their source before getting caught.

Comparison of error propagation in Result types versus exceptions

Teams working in established codebases with thousands of exception-throwing functions face a migration challenge. Converting one function to return Result<T, E> requires updating every caller. Exceptions remain compatible with the existing architecture. For greenfield projects or isolated modules, Result types impose no integration cost.

Exception performance in modern JavaScript engines imposes negligible overhead under normal control flow. Throwing and catching exceptions costs more than returning a value, but the difference matters only in tight loops where exceptions occur frequently. Real applications rarely hit performance limits from exception handling. Result types have similarly negligible performance impact because they compile to plain object returns.

The learning curve for Result types affects teams differently based on their background. Engineers familiar with Rust, Go, or functional programming recognize the pattern immediately. Teams working exclusively in JavaScript/TypeScript need time to internalize the explicit error handling mindset. The pattern requires consistent adoption across a codebase to provide value.

Exception familiarity gives them an advantage for quick prototyping and small projects. Every JavaScript developer understands try/catch syntax. Result types require teaching the team a new pattern before they can use it effectively. For projects where time to market matters more than long-term maintainability, exceptions offer a faster path.

Error Discrimination Patterns That Actually Work in Production

Catching exceptions in TypeScript produces values typed as unknown. The type system provides no information about what gets thrown. Developers must narrow the caught value to specific error types before accessing error properties safely.

class NetworkError extends Error {
  constructor(public statusCode: number, message: string) {
    super(message);
    this.name = 'NetworkError';
  }
}

class ValidationError extends Error {
  constructor(public field: string, message: string) {
    super(message);
    this.name = 'ValidationError';
  }
}

function processRequest(data: unknown) {
  try {
    validateData(data);
    sendToServer(data);
  } catch (e) {
    if (e instanceof NetworkError) {
      console.error(`Network failed with status ${e.statusCode}`);
      return;
    }
    if (e instanceof ValidationError) {
      console.error(`Validation failed on field ${e.field}`);
      return;
    }
    // Unknown error - rethrow or log
    throw e;
  }
}

The instanceof operator narrows the type of e within each conditional block. TypeScript understands that after e instanceof NetworkError passes, e has type NetworkError in that branch. This pattern works for class-based errors that extend Error or implement distinct prototypes.

Custom error classes should always extend Error and set a distinctive name property. This practice ensures stack traces remain accurate and error monitoring tools can distinguish error types. The built-in Error.prototype.name gets set automatically when using class syntax with extends Error.

Type guard functions provide an alternative to instanceof checks when errors do not share a common base class. A type guard returns a boolean and uses a type predicate to tell TypeScript what type the value has when the guard returns true.

interface APIError {
  code: string;
  message: string;
}

function isAPIError(e: unknown): e is APIError {
  return (
    typeof e === 'object' &&
    e !== null &&
    'code' in e &&
    'message' in e &&
    typeof (e as APIError).code === 'string'
  );
}

function handleResponse(response: unknown) {
  try {
    processResponse(response);
  } catch (e) {
    if (isAPIError(e)) {
      console.error(`API error ${e.code}: ${e.message}`);
      return;
    }
    console.error('Unknown error:', e);
  }
}

The type guard performs runtime validation that the caught value has the expected shape. This pattern works when integrating with third-party APIs that throw plain objects rather than Error instances. The guard must check every required property because unknown values can be anything.

Error discrimination flow using instanceof and type guards

Error discrimination patterns in TypeScript catch blocks

Some codebases throw string literals or plain objects instead of Error instances. These patterns work at runtime but complicate error handling. Catching a string provides no stack trace and no way to distinguish error types beyond string parsing. Modern code should always throw Error instances or subclasses.

The zod library provides a .safeParse() method that returns a discriminated union instead of throwing. This pattern bridges the gap between validation libraries that throw and Result-type error handling.

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
});

function validateUser(data: unknown) {
  const result = UserSchema.safeParse(data);
  if (!result.success) {
    // result.error is a ZodError with detailed validation failures
    console.error(result.error.format());
    return null;
  }
  // result.data is typed as { id: string; email: string }
  return result.data;
}

The .safeParse() API demonstrates how libraries can provide both throwing and non-throwing variants. The standard .parse() method throws a ZodError on validation failure. The .safeParse() method returns { success: true; data: T } or { success: false; error: ZodError } without throwing. This gives callers the choice between exceptions and Result types per call site.

Documenting Throws Behavior for Teams and Tools

Teams that continue using exceptions need documentation strategies that scale. JSDoc @throws tags work when combined with linting rules that enforce their presence and code review processes that verify accuracy. The pattern relies on human discipline but provides value when applied consistently.

/**
 * Connects to the database with retry logic
 * @throws {ConnectionError} when all retry attempts fail
 * @throws {AuthenticationError} when credentials are invalid
 * @throws {TimeoutError} when connection exceeds deadline
 */
async function connectDatabase(config: DatabaseConfig): Promise<Connection> {
  // implementation
}

The eslint-plugin-jsdoc package includes rules that enforce @throws documentation. The require-throws rule checks that functions containing throw statements have corresponding @throws tags. Configuration options control whether the rule applies to all functions or only exported ones. Related tooling context shows how modern linters handle JSDoc validation.

Code review checklists should include verification that @throws tags match actual throw behavior. When a pull request modifies a function's error handling, reviewers check that JSDoc comments get updated accordingly. This manual process catches most documentation drift but depends on reviewer attention.

Documentation flow for throw behavior in team workflows

TypeDoc and similar documentation generators parse @throws tags into generated reference documentation. The official TypeDoc documentation (accessed via npm package typedoc version 0.26.x) shows that @throws tags appear in a dedicated "Throws" section of function documentation. This makes error behavior visible in generated API docs but does not affect compilation.

Some teams encode error types in function names as a lightweight alternative to comprehensive JSDoc. Functions named fetchUserOrThrow signal explicitly that they throw on failure, while tryFetchUser suggests they return null or undefined. This convention provides no type safety but improves code readability.

Error boundaries in React applications demonstrate a practical exception-based pattern that works without type system support. A component wraps children and catches errors that propagate during rendering. Related distributed context explores how error tracking spans service boundaries.

class ErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean; error?: Error }
> {
  state = { hasError: false, error: undefined };

  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    logErrorToService(error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return <ErrorFallback error={this.state.error} />;
    }
    return this.props.children;
  }
}

Error boundaries rely on React's lifecycle methods rather than TypeScript's type system. The pattern works because React guarantees when componentDidCatch gets called, eliminating the need for static analysis to track throw behavior through the component tree.

Frequently Asked Questions

Why doesn't TypeScript just add a throws keyword like Java?

JavaScript has unchecked exceptions and no runtime enforcement of throw declarations. TypeScript follows JavaScript semantics and avoids features that require fundamental runtime changes. The complexity of accurately modeling JavaScript's dynamic throw behavior through function references, callbacks, and async operations exceeds the benefit.

Can I use a compiler plugin to add throw type checking?

No compiler plugin system exists in TypeScript that allows custom type checking logic. The TypeScript compiler architecture does not support plugins that extend the type checker. Teams must work within the type system's built-in capabilities or use external tools like custom linters.

Do Result types work with async/await?

Result types work with async/await when the Promise resolves to a Result. Functions return Promise<Result<T, E>> instead of throwing. Callers await the Promise and then unwrap the Result with the same patterns used for synchronous code. The neverthrow library provides .asyncMap() and similar utilities for async Result composition.

How do I convert an exception-throwing library to use Result types?

Wrap library calls in adapter functions that catch exceptions and return Results. The adapter provides a typed boundary between exception-based external code and Result-based internal code. This pattern contains the exception handling at the integration point without requiring changes to the library itself.

What happens to stack traces when using Result types?

Result types preserve stack traces when the error case contains an Error instance. Creating errors with new Error() captures the call stack at that point. Result types simply return the error rather than throwing it, so the stack trace remains intact and accessible through the error's .stack property.

What to Do Until (If Ever) TypeScript Gets Throw Types

TypeScript will likely never support throw types given the language's design constraints and JavaScript's runtime semantics. The core team has not signaled any movement toward this feature in recent releases. Teams building production TypeScript applications must accept that exception typing will remain outside the type system's guarantees.

Result types provide the strongest alternative for codebases that need verifiable error handling. The pattern requires architectural commitment and training investment, but it delivers compile-time verification that exceptions cannot match. New projects should consider Result types from the start when error handling matters more than code brevity.

Exception-based codebases should combine @throws JSDoc with linter enforcement and code review processes. This approach lacks type system verification but provides human-readable documentation that scales to large teams. The pattern works when the team values familiar exception syntax and accepts manual verification during review.

Error discrimination using instanceof checks and type guards makes exception handling safer when exceptions remain the chosen approach. Every catch block should narrow the caught value to specific error types before accessing properties. This pattern prevents runtime errors from assumed error shapes while working within TypeScript's type system.

The library architecture patterns that underpin maintainable TypeScript projects apply equally to error handling strategy. Choose one approach and apply it consistently across the codebase rather than mixing patterns that create confusion at boundaries. The consistency matters more than the specific choice between Results and exceptions for most applications.

Claude Code Custom System Prompts in 2026: Overriding Defaults, Appending Instructions, and What You Cannot Change

jsmanifest — Mon, 02 Nov 2026 06:06:52 +0000

Claude Code Custom System Prompts in 2026: Overriding Defaults, Appending Instructions, and What You Cannot Change

Developers add custom instructions to Claude Code, restart the session, and watch Claude ignore them. The instructions sit in a CLAUDE.md file, or a settings.json key, or an --append-system-prompt flag, but Claude still responds with the default behavior. This confusion stems from a misunderstanding of where each layer applies and what the system prompt actually controls.

Claude Code provides three distinct mechanisms for shaping behavior: replacing or appending to the system prompt with CLI flags, defining persistent project context in CLAUDE.md files, and configuring output styles that transform how Claude formats responses. Each mechanism operates at a different layer of the request cycle, and mixing them without understanding their boundaries produces configuration that appears broken but is working exactly as designed.

The system prompt itself is not a single editable file. Claude Code builds it from multiple sources at request time, and certain parts remain locked regardless of configuration. Understanding which parts you can change, which require a different mechanism, and which remain fixed is the difference between instructions that work and instructions that vanish.

This post examines the three ways to customize Claude Code behavior, explains what each mechanism controls, and clarifies which built-in behaviors cannot be changed no matter which layer you modify.

Key Takeaways

Claude Code builds the system prompt from multiple sources; replacing or appending text with CLI flags changes the core identity and tool guidance, while CLAUDE.md injects project context into the conversation separately.
The --system-prompt flag replaces the entire default prompt including tool descriptions and safety instructions, while --append-system-prompt preserves the default and adds extra rules on top.
CLAUDE.md files do not modify the system prompt; they inject content into the conversation as project context that Claude reads alongside the system prompt.
Output styles, skills, and permission rules shape behavior through separate mechanisms that remain active regardless of system prompt customization.
Built-in safety instructions, tool definitions, and API-level constraints cannot be overridden through any system prompt flag or configuration file.

Understanding System Prompt Presets: claude_code vs Custom Strings

Claude Code does not expose the full default system prompt as an editable file. The official documentation confirms this: "Claude Code's system prompt isn't published. To give Claude standing instructions, use CLAUDE.md files or the --append-system-prompt flag." Developers who expect a single text file controlling Claude's identity will not find one, because the prompt assembles from multiple internal sources at runtime.

The default prompt includes the following components:

Core identity and role definition
Tool descriptions and usage guidance for each available capability
Safety and security instructions
Coding conventions and best practices
Output formatting rules

When developers pass --system-prompt or --system-prompt-file, they replace all of these components with their own text. Claude Code discards the default identity, tool guidance, and safety instructions, leaving the developer responsible for defining everything from scratch.

This replacement makes sense for non-coding agents where Claude Code's default identity does not fit the task, but it creates problems when developers simply want to add domain-specific rules without rebuilding the entire prompt. For that use case, --append-system-prompt preserves the default and adds extra instructions after it.

The choice between replacement and append determines whether developers inherit Claude Code's built-in tool guidance. A replaced prompt loses descriptions of how the Bash tool works, when to use Read versus Write, and which permission checks apply before tool execution. An appended prompt keeps those descriptions and layers new instructions on top.

Appending Instructions: Extending the Default Without Starting From Scratch

The --append-system-prompt and --append-system-prompt-file flags let developers extend the default prompt without replacing it. This preserves Claude Code's identity as a coding assistant while adding project-specific conventions, output requirements, or domain context.

A typical use case: enforcing a consistent code review format. Developers want Claude to check for specific patterns in every review without changing how Claude uses tools or responds to questions. Appending instructions achieves this:

// Start Claude Code with custom review rules appended
// Shell command:
// claude --append-system-prompt-file ./review-rules.txt

// Contents of review-rules.txt:
When reviewing code, always check for:
1. Missing error handling in async functions
2. Hardcoded configuration values that should be environment variables
3. Console.log statements that should be removed before production
4. Tests that need updating after implementation changes

Format your review as:
- Summary (2-3 sentences)
- Findings (bulleted list with file:line references)
- Risk level (low/medium/high)

Claude receives the default system prompt followed by a blank line and then the appended text. The blank line separates the default instructions from the custom rules, making the boundary clear when debugging what Claude sees.

Developers can combine both inline text and file contents by passing both --append-system-prompt and --append-system-prompt-file in the same command (requires Claude Code v2.1.283 or later). The file contents appear first, followed by a blank line, then the inline text:

// Combine file and inline instructions
// Shell command:
// claude --append-system-prompt-file ./style.md --append-system-prompt "Always reply in French"

// Claude receives:
// 1. Default system prompt
// 2. Blank line
// 3. Contents of style.md
// 4. Blank line
// 5. "Always reply in French"

This ordering ensures that persistent style rules from the file remain stable across runs while allowing per-invocation overrides through the inline flag.

Claude Code system prompt layers

The appended text applies to a single session. Starting a new session without the flags returns to the default prompt. Developers who need persistent instructions that apply across all sessions should use CLAUDE.md files instead, which inject content at a different layer.

CLAUDE.md vs System Prompts: What Actually Goes Where

CLAUDE.md files do not modify the system prompt. This distinction trips up developers who expect CLAUDE.md to work like a persistent --append-system-prompt, but CLAUDE.md operates through a separate mechanism that injects content into the conversation as project context.

The Agent SDK documentation states: "CLAUDE.md takes a different path: the SDK reads it and injects its content into the conversation as project context, so it shapes behavior alongside whichever system prompt you choose." This injection happens after the system prompt is built, meaning CLAUDE.md cannot override tool guidance or safety instructions that live in the system prompt layer.

Aspect	System Prompt Flags	CLAUDE.md Files
Scope	Single session	Persistent across sessions
Timing	Applied at prompt assembly	Injected into conversation
Can override tool guidance	Yes (with --system-prompt)	No
Can define project conventions	Yes (with --append)	Yes
Requires restart after edit	No (takes effect immediately)	No (watched for changes)
Location	CLI flag	Project .claude/ directory

CLAUDE.md excels at defining what the project is, what conventions it follows, and what context Claude needs to understand it. System prompt flags excel at defining who Claude is and how Claude should respond. When developers put project conventions in the system prompt or try to redefine Claude's identity in CLAUDE.md, the configuration fights against the mechanism's design.

A well-structured setup uses CLAUDE.md for project facts:

// .claude/CLAUDE.md contents:
# Project: TypeScript API Server

This project uses:
- Express 4.18 with TypeScript 5.3
- Jest for testing with 80%+ coverage requirement
- Zod for runtime validation
- Prisma 5.x for database access

Conventions:
- All API routes live in src/routes/
- Database models use singular names (User, not Users)
- Environment variables are required at startup (fail fast)
- Error responses follow RFC 7807 Problem Details format

And system prompt flags for response requirements:

// Pass this flag when starting Claude Code:
// --append-system-prompt "When suggesting code changes, always include the full file path and a brief explanation of why the change is needed"

This separation lets developers change project facts without touching how Claude formats responses, and change response formatting without modifying project documentation.

What You Cannot Override: Built-In Safety, Tool Definitions, and Hard Limits

Certain parts of Claude Code behavior remain fixed regardless of system prompt configuration. These restrictions protect against unsafe operations, ensure consistent tool behavior, and enforce API-level constraints that no client-side configuration can bypass.

Three categories of behavior cannot be overridden:

Safety and security instructions. Claude Code includes built-in rules that prevent certain operations even when the system prompt requests them. These rules operate at a layer below the system prompt, meaning a custom --system-prompt text cannot remove them. Examples include refusal to generate malware, restrictions on processing sensitive data without explicit permission, and guardrails against executing commands that could compromise the system.

Tool definitions and behavior. The tools Claude Code exposes (Bash, Read, Write, Edit, and others) have fixed definitions that describe their parameters, when to use them, and what they return. A custom system prompt can provide additional guidance on tool usage, but it cannot change the tool's signature or disable built-in tool restrictions. For instance, developers cannot use --system-prompt to make the Read tool bypass permission checks or force the Bash tool to run commands without approval when project settings require it.

API and model constraints. Token limits, rate limits, and model capabilities are set by the Anthropic API and cannot be increased through configuration. A system prompt that requests "unlimited context window" has no effect because the constraint exists at the API layer, not in Claude Code's client logic.

Developers who attempt to override these restrictions through creative prompt engineering will find that Claude Code silently ignores the instructions or Claude refuses the request. The official documentation warns: "Replacing drops all of the default prompt, including tool guidance and safety instructions, so you take responsibility for whatever your task still needs." This warning applies to guidance developers can provide, not to safety checks they cannot remove.

The distinction matters when debugging why certain instructions fail. If a custom system prompt asks Claude to "always read .env files without asking," the request fails not because the prompt is malformed but because permission checks happen after the prompt is processed. The solution is not better prompt engineering but configuring permissions through the separate permissions mechanism.

Real-World Patterns: Output Styles, Skills, and Hooks That Shape Behavior Outside the System Prompt

Claude Code provides three additional mechanisms for shaping behavior that operate independently of the system prompt: output styles, skills, and hooks. Each mechanism targets a different aspect of Claude's responses, and understanding when to use each prevents configuration conflicts.

Output styles transform how Claude formats responses without changing the underlying reasoning or tool usage. An output style might enforce markdown structure, add specific headers to code blocks, or require responses to follow a template. Output styles apply after Claude generates a response, meaning they cannot change which tools Claude chooses or what logic Claude follows. The official documentation states: "an output style changes the instructions Claude Code gives Claude for every response."

Skills add specific capabilities that Claude loads on demand. A skill defines when to run (through YAML frontmatter), what dynamic context to inject (through command substitution), and what instructions to follow when active. Skills operate through the conversation context layer, not the system prompt layer, which means they remain available even when developers replace the system prompt entirely.

Hooks execute code at specific points in the request lifecycle: before a request is sent, after Claude responds, or when specific events occur. Hooks can modify the request, transform the response, or trigger external actions. They run in the Claude Code runtime, not as instructions to Claude, which gives them capabilities that system prompts cannot replicate.

A practical example demonstrates the difference. Developers building a documentation generator want Claude to:

Read TypeScript source files
Extract JSDoc comments and type definitions
Format the output as markdown with specific section headers
Inject the result into a template
Write the final documentation to a file

This workflow spans multiple mechanisms:

// 1. CLAUDE.md defines project conventions
// .claude/CLAUDE.md:
# Documentation Standards
All exported functions must have JSDoc comments with @param and @returns tags.
Type definitions use TypeScript 5.3 syntax.

// 2. Skill provides dynamic context and registers its own Stop hook
// .claude/skills/doc-gen/SKILL.md:
---
description: Generate documentation from TypeScript source files
hooks:
  Stop:
    - hooks:
        - type: command
          command: "${CLAUDE_SKILL_DIR}/write-docs.sh"
---
## Current files
!`find src -name "*.ts" -not -path "*/test/*"`

## Instructions
Extract JSDoc comments and type definitions from the files above.

// 3. Output style enforces format
// .claude/output-styles/docs.md:
Format documentation as:
## Function Name
Description from JSDoc

**Parameters:**
- param: type - description

**Returns:** return type - description

// 4. The skill's own hook writes the response to a file
// .claude/skills/doc-gen/write-docs.sh:
#!/bin/bash
# Reads the Stop hook's JSON input from stdin and saves the final response
python3 -c "import json,sys; d=json.load(sys.stdin); open('./docs/api.md','w').write(d['last_assistant_message'])"

Attempting to implement this workflow through a single --system-prompt flag would fail because the system prompt cannot read files dynamically (skill functionality), format output conditionally (output style functionality), or write files after Claude responds (hook functionality). Each mechanism exists because it solves a problem the system prompt cannot address alone.

Claude Code configuration mechanisms

The documentation's guidance remains relevant: "For persistent personas you can switch between and share across a project, use output styles. For project conventions Claude should always follow, use CLAUDE.md." System prompt flags are for identity and per-invocation instructions, not for persistent behavior that should survive across sessions.

Common Mistakes: Why Your System Prompt Feels Ignored

Developers report that Claude ignores custom system prompts, but the problem usually sits in one of three areas: recording behavior, layer mismatches, or permission conflicts. Understanding these failure modes prevents hours of debugging configuration that is working correctly but not in the way developers expect.

Recording behavior in resumed conversations. By default, Claude Code builds the system prompt once on the first request of a conversation and records it. Later requests in the same conversation reuse that recorded prompt, even if developers pass different --system-prompt flags when resuming with --continue. The official documentation explains: "Until the conversation is compacted, every later request uses that recorded prompt, including after you return to the conversation with --resume or --continue."

This design optimizes for consistent behavior across a multi-turn conversation, but it surprises developers who expect system prompt changes to apply immediately. The solution is passing --system-prompt-snapshot off, which rebuilds the prompt on every request. This flag is essential during development when iterating on prompt wording:

// Iterate on system prompt wording without starting new sessions
// Shell command:
// claude --append-system-prompt "Draft rules v3" --system-prompt-snapshot off --continue

// Each run rebuilds the prompt with the new text
// Perfect for testing different phrasings

Layer mismatches. Developers put instructions in CLAUDE.md expecting them to override tool behavior, or they put project facts in --system-prompt expecting persistence across sessions. Both configurations fail because the instructions sit in the wrong layer. CLAUDE.md cannot override tool guidance that lives in the system prompt, and system prompt flags do not persist across sessions without being passed on every launch.

The fix is moving instructions to the correct layer: tool behavior overrides go in --system-prompt (which replaces the default including tool guidance), project conventions go in CLAUDE.md, and per-session response formatting goes in --append-system-prompt or output styles.

Permission conflicts. A system prompt can request specific tool behavior, but permission checks run separately and take precedence. If a system prompt says "always read package.json without asking" but project permissions require approval for Read operations, the permission check blocks the read regardless of what the system prompt requests. The official documentation confirms: "an allowed-tools grant goes through the normal permission flow."

Developers who encounter this conflict must configure permissions through the separate permissions mechanism (allow/ask/deny rules in settings.json or through permission prompts) rather than attempting to bypass permissions through prompt engineering. The permissions documentation describes the full syntax, and our production guide covers common permission patterns.

A fourth category of confusion stems from character restrictions in skill names and frontmatter. If a skill appears to load but its command does not work, the official documentation lists characters that Claude Code refuses: "Claude Code refuses a command name or a frontmatter name that contains characters such as: zero-width space or control character, private-use or unassigned character, character that changes text direction, blank other than one plain space, < or >." Renaming the skill folder or editing the name field in frontmatter resolves the issue, and the debug log (claude --debug) shows which names were refused.

Frequently Asked Questions

How do I make my custom system prompt persist across all sessions?

You cannot make a --system-prompt or --append-system-prompt flag persist automatically. These flags apply to the session you start them with. For instructions that should apply to all sessions in a project, put them in a CLAUDE.md file in the project's .claude/ directory. For cross-project conventions, create a script or alias that starts Claude Code with your preferred flags.

Why does Claude ignore my CLAUDE.md file?

CLAUDE.md does not modify the system prompt and cannot override built-in tool behavior or safety instructions. It injects content into the conversation as project context, which means it works best for defining what the project is and what conventions it follows, not for changing how Claude uses tools or formats responses. If your CLAUDE.md contains instructions about tool usage or response formatting, move them to an --append-system-prompt flag or an output style.

Can I disable Claude Code's safety instructions through a custom system prompt?

No. Safety and security checks operate at a layer below the system prompt. Even when you replace the entire default prompt with --system-prompt, the API-level safety checks remain active. This restriction exists to prevent accidental or intentional misuse and cannot be bypassed through any client-side configuration.

What happens when I pass both --system-prompt and --append-system-prompt?

Claude Code uses both. The --system-prompt flag replaces the default prompt, and then --append-system-prompt adds your extra text after that replacement. This combination is useful when you need a non-coding identity (through replacement) but still want to add per-invocation instructions (through append). With Claude Code v2.1.283 or later, you can also combine the inline and file forms of the same flag.

How do I debug which system prompt Claude is actually receiving?

Claude Code does not publish the full system prompt text, but you can confirm which sources loaded by running /status inside a session and checking the "Setting sources" line. For more details, run claude --debug from your shell and search the debug log for prompt-related entries. The log shows which settings files loaded and which system prompt flags applied, though it does not dump the full prompt text.

Conclusion: Choosing the Right Layer for Your Custom Instructions

System prompt customization in Claude Code requires understanding three distinct layers: the prompt itself (controlled through CLI flags), project context (injected through CLAUDE.md), and behavior modifications (implemented through output styles, skills, and hooks). Developers who put every instruction in the system prompt discover that some work, some vanish, and some conflict with other mechanisms. The configuration is not broken but is fighting against the layer where each mechanism operates.

Replace the system prompt when the default identity does not fit the task. Append to it when you need per-invocation instructions that preserve tool guidance. Use CLAUDE.md for project facts that should persist across sessions. Configure output styles for response formatting, skills for on-demand capabilities, and hooks for request lifecycle modifications. The official documentation at code.claude.com/docs covers each mechanism in detail, and the memory strategies guide explores how these layers interact with Claude's context handling.

Next.js Prefetching in App Router: How `` Partial Prefetch Works and Why Your Pages Still Feel Slow

jsmanifest — Sun, 01 Nov 2026 06:07:18 +0000

Next.js Prefetching in App Router: How `<Link>` Partial Prefetch Works and Why Your Pages Still Feel Slow

Developers adopt Next.js App Router expecting server components to eliminate client-side waterfalls and prefetching to deliver instant navigation. The reality surprises them: links feel sluggish, dynamic routes block for seconds, and the DevTools network tab shows requests firing only after the user clicks. The prefetch happened, the data arrived, but the navigation still waits.

The confusion stems from three behaviors that collide in production: partial prefetch stops at the first Suspense boundary instead of loading the full page, the router cache expires prefetched data after 30 seconds for dynamic routes, and the client cannot render anything until the server responds with the missing pieces. The result is a server-driven app that feels slower than the client-side SPA it replaced.

Next.js 16.3 introduces partial prefetching as an opt-in feature, giving developers fine-grained control over what loads before navigation. Combined with the new cache components primitive, teams can mark reusable UI as cacheable and let Next.js extract loading shells from any route, not just routes with a loading.tsx file. The client now has enough data to render an instant transition, and the server streams dynamic content as it resolves.

This post explains how App Router prefetching works under the hood, why the default behavior creates slow navigations, and how to adopt the new primitives to make every link click feel instant without breaking dynamic content.

Key Takeaways

Next.js App Router partial prefetch (the default) stops at the first Suspense boundary, not the full page, causing slow navigations when routes lack explicit loading shells.
The router cache expires prefetched data after 30 seconds for dynamic routes and 5 minutes for static routes, triggering re-fetches on click if the user waits too long.
Next.js 16.3's partial prefetching and cache components let developers mark reusable UI as cacheable and control exactly what loads before navigation.
Instant Insights in the Next.js DevTools automatically surfaces slow navigations during development, eliminating guesswork about which links need optimization.
Full prefetch with prefetch={true} loads the entire destination page ahead of time, but costs bandwidth and can serve stale personalized content if cached data expires.

How Next.js Link Prefetching Actually Works in App Router

The <Link> component in Next.js App Router triggers prefetching when it enters the viewport or when the user hovers over it. The exact behavior depends on the prefetch prop and whether the destination route is static or dynamic.

By default, <Link> uses prefetch="auto", which means Next.js decides what to prefetch based on the route type. For static routes, the full route loads. For dynamic routes, Next.js fetches the route down to the first loading.tsx boundary, a behavior called partial prefetch.

The distinction between static and dynamic routes matters because Next.js treats them differently at build time. A route is static if it contains no dynamic segments (like [id]), no generateStaticParams is missing, and it does not read request-specific data like cookies or headers. Everything else is dynamic.

// app/blog/page.tsx - static route
export default function BlogPage() {
  return <div>Blog posts render at build time</div>;
}

// app/blog/[slug]/page.tsx - dynamic route
export default function PostPage({ params }: { params: { slug: string } }) {
  // Reads dynamic segment, so Next.js treats this as dynamic
  return <div>Post: {params.slug}</div>;
}

When a user hovers over a <Link href="/blog/post-1">, Next.js sends a request to the server. For a static route, the server returns the pre-rendered HTML and RSC payload. For a dynamic route, the server returns only the layout and any shared UI down to the first Suspense boundary, then stops. The page component itself does not load until the user clicks.

The official Next.js documentation (as of version 16.3) describes this behavior in the prefetch prop reference: "For dynamic routes, the partial route down to the nearest segment with a loading.js boundary will be prefetched." If no loading.tsx file exists, the prefetch ends at the layout, and the navigation blocks until the server responds with the page.

The router cache stores prefetched data with a time-to-live (TTL) that depends on the route type. Static routes cache for 5 minutes. Dynamic routes cache for 30 seconds. After the TTL expires, clicking the link triggers a new server request even if the prefetch completed successfully.

This explains why navigations sometimes feel instant and sometimes block. If the user clicks within 30 seconds of hovering, the cached data is fresh and the navigation completes immediately. If the user waits 31 seconds, the cache expires, and the client must wait for the server to re-render the route before the navigation can proceed.

Partial Prefetch vs Full Prefetch: What Gets Loaded When

The prefetch prop on <Link> accepts three values: "auto" (the default), true, and false. Each produces different behavior and costs.

prefetch="auto" defers to Next.js to decide what to load. For static routes, this means the full route. For dynamic routes, this means a partial prefetch that stops at the first loading.tsx boundary. The goal is to balance performance with bandwidth: prefetch enough to make navigation feel instant without loading content the user may never see.

prefetch={true} forces a full prefetch for both static and dynamic routes. The client downloads the entire page, including all data-fetching and rendering, before the user clicks. This guarantees instant navigation but wastes bandwidth if the user never visits the link. It also introduces stale data problems for personalized routes: if the prefetched page contains user-specific content, and the user waits long enough for the cache to expire, clicking the link shows stale content until the server responds with fresh data.

prefetch={false} disables prefetching entirely. The client requests the route only after the user clicks. This saves bandwidth but guarantees a slow navigation because the client must wait for the server to render the page before the transition can complete.

Next.js 16.3 changes the behavior when partial prefetching is enabled via partialPrefetching: true in next.config.ts. With this flag, prefetch="auto" now prefetches the route's app shell (the static and cached content) instead of stopping at the first loading.tsx boundary. The app shell includes layouts, templates, and any components marked with 'use cache', giving the client enough data to render a loading state immediately on click.

Prefetch value	Static route behavior	Dynamic route behavior	Router cache TTL	Best for
`"auto"` (default)	Full route	Partial (to first `loading.tsx`)	Static: 5min, Dynamic: 30s	Most links
`true`	Full route	Full route	Static: 5min, Dynamic: 30s	Critical navigation paths
`false`	No prefetch	No prefetch	N/A	Rarely-visited routes, infinite scroll lists
`"auto"` (with `partialPrefetching: true`)	App shell + cached content	App shell + cached content	Configurable per cache tag	Next.js 16.3+ apps

The tradeoff between partial and full prefetch becomes clear in a dashboard app. A sidebar contains 20 links to different reports. Full prefetch downloads all 20 pages when the sidebar renders, consuming megabytes of bandwidth and server resources even if the user only views one report. Partial prefetch downloads the shell for each page (layouts, navigation, headers) but waits to load report-specific data until the user clicks. The navigation feels instant because the shell paints immediately, and the data streams in as it resolves.

// app/dashboard/layout.tsx
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="dashboard">
      <nav>
        {/* Partial prefetch: loads shell, not data */}
        <Link href="/dashboard/sales">Sales Report</Link>
        <Link href="/dashboard/inventory">Inventory</Link>
        <Link href="/dashboard/analytics">Analytics</Link>
      </nav>
      <main>{children}</main>
    </div>
  );
}

The diagram shows why partial prefetch feels faster for the initial shell render but slower for the complete page, while full prefetch either delivers the entire page instantly or serves stale content if the cache expired. Choosing the right strategy depends on whether the route contains dynamic content that changes frequently.

The Router Cache Problem: When Prefetched Data Goes Stale

The router cache in Next.js App Router exists to avoid redundant server requests. When a prefetch completes, Next.js stores the result in memory with a TTL. Subsequent navigations to the same route read from the cache instead of hitting the server, making back-and-forth navigation instantaneous.

The problem surfaces when the TTL expires before the user clicks. For dynamic routes, 30 seconds is short enough that normal user behavior (reading content, scrolling, comparing options) exhausts the cache before the navigation happens. The user clicks, the cache check fails, and the client blocks while waiting for the server to re-render the route.

This behavior surprises developers because the prefetch succeeded. The DevTools network tab shows the request completing with a 200 status. But when the user clicks 35 seconds later, a second identical request fires, and the navigation waits for that response before proceeding. The prefetch wasted bandwidth and delivered no performance benefit.

The stale data problem is worse for personalized routes. Consider a product page that shows the user's cart count in the header. If the page prefetches when the user hovers the link, and the user adds items to the cart before clicking, the prefetched page shows the old cart count until the new server response arrives. The transition looks instant, but the cart count is wrong for 200-300ms, creating a flicker as the correct data streams in.

Next.js addressed this in 16.3 by tying cache invalidation to the 'use cache' directive. When a component or function is marked with 'use cache', Next.js generates a cache key based on the function's arguments and the user's session. If the arguments or session change, the cache key changes, and the cached data is no longer valid. This lets developers opt specific components into granular caching while keeping the rest of the page fresh.

// app/dashboard/sales/page.tsx
import { unstable_cache } from 'next/cache';

async function getSalesData(userId: string) {
  'use cache';
  const response = await fetch(`/api/sales?user=${userId}`);
  return response.json();
}

export default async function SalesPage({ params }: { params: { userId: string } }) {
  const data = await getSalesData(params.userId);

  return (
    <div>
      <h1>Sales Report</h1>
      {/* This data is cached per user and stays fresh across navigations */}
      <pre>{JSON.stringify(data, null, 2)}</pre>
    </div>
  );
}

The official Next.js 16.3 release notes state: "It's more explicit and composable than our previous server-side caching APIs, and now, it also brings client-side caching to Next.js for the first time." The 'use cache' directive integrates with prefetching by letting the router cache store function-level results instead of full routes. When a prefetch happens, Next.js extracts the cached data, bundles it with the shell, and sends it to the client. The user clicks, the shell renders instantly, and only the non-cached dynamic data requires a server round-trip.

The cache key mechanism solves the stale data problem but introduces a new complexity: cache invalidation. If the sales data changes server-side while the client holds a cached copy, the user sees outdated information until the cache expires or the route re-validates. Next.js provides revalidation APIs (revalidatePath, revalidateTag) to expire caches on demand, but developers must call them explicitly when data changes.

Router cache diagram showing TTL expiration and re-fetch behavior

The image illustrates how the router cache expires after the TTL and triggers a new server request, even when the original prefetch completed successfully. The gap between prefetch and click determines whether the navigation feels instant or blocks.

Controlling Prefetch Behavior: Practical Code Examples

Developers control prefetching at three levels: per-link via the prefetch prop, per-route via loading.tsx files, and globally via next.config.ts flags.

The prefetch prop is the most direct control. Setting prefetch={false} disables prefetching for a specific link, useful for links in infinite scroll lists where prefetching would waste bandwidth. Setting prefetch={true} forces a full prefetch, useful for critical navigation paths like the main call-to-action on a landing page.

// app/components/product-list.tsx
'use client';

export default function ProductList({ products }: { products: Product[] }) {
  return (
    <div className="grid">
      {products.map((product) => (
        <Link
          key={product.id}
          href={`/product/${product.id}`}
          // Disable prefetch for long lists to save bandwidth
          prefetch={false}
        >
          {product.name}
        </Link>
      ))}
    </div>
  );
}

The loading.tsx file provides a route-level loading shell that prefetching uses to render an instant transition. When a dynamic route includes a loading.tsx file, partial prefetch stops at that file and sends the loading component to the client. The user clicks, the loading state renders immediately, and the page content streams in as the server resolves data-fetching.

// app/blog/[slug]/loading.tsx
export default function Loading() {
  return (
    <div className="blog-post-skeleton">
      <div className="skeleton-title" />
      <div className="skeleton-author" />
      <div className="skeleton-content" />
    </div>
  );
}

Without loading.tsx, partial prefetch has nothing to send, so the navigation blocks until the full page arrives. The Next.js DevTools Instant Insights panel highlights this as a slow navigation and suggests adding a loading file.

Next.js 16.3 adds two config flags that change prefetching behavior globally. Setting cacheComponents: true enables the new cache components primitive, letting developers mark reusable UI with 'use cache' and have Next.js extract it during prefetch. Setting partialPrefetching: true changes the default prefetch="auto" behavior from "stop at first loading.tsx" to "prefetch app shell plus cached content."

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
};

export default nextConfig;

These flags unlock fine-grained control over what loads before navigation. A product page can mark the header, footer, and navigation as cached, while leaving product-specific content (price, availability, reviews) dynamic. The prefetch sends the shell, the user clicks, the shell renders instantly, and the dynamic content streams in.

// app/product/[id]/page.tsx
import { Suspense } from 'react';

async function Header() {
  'use cache';
  return <header>Site Header</header>;
}

async function ProductDetails({ id }: { id: string }) {
  const product = await fetch(`/api/products/${id}`).then(res => res.json());

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.price}</p>
    </div>
  );
}

export default function ProductPage({ params }: { params: { id: string } }) {
  return (
    <>
      <Header />
      <Suspense fallback={<div>Loading product...</div>}>
        <ProductDetails id={params.id} />
      </Suspense>
    </>
  );
}

The cache components approach solves the stale data problem by caching at the component level instead of the route level. The header never changes, so it stays cached indefinitely. The product details change frequently, so they skip the cache and fetch fresh data on every navigation. The user sees an instant shell render followed by a smooth stream of dynamic content, no flicker, no stale data.

Next.js 16.3 Instant Navigations and the Future of Prefetching

Next.js 16.3 introduces Instant Navigations, a suite of features designed to make server-rendered apps feel as responsive as client-side SPAs without sacrificing the benefits of server rendering. The headline feature is partial prefetching, which builds on the cache components primitive to extract loading shells from any route, not just routes with a loading.tsx file.

The official Next.js 16.3 announcement states: "Next.js can extract this UI and load it into the client prior to a navigation, making your app feel as snappy as an SPA once users start clicking around it." The key word is "extract." Instead of requiring developers to manually define loading shells in separate files, Next.js analyzes the route's component tree, identifies cached components, and bundles them with the prefetch response. The client receives a ready-to-render shell even if the route has no loading.tsx file.

Partial prefetching also changes how prefetch payloads are structured. In prior versions, a prefetch request returned a monolithic RSC payload containing the entire route. In 16.3, the payload includes three layers: the app shell (layouts, templates, cached components), URL-specific data (dynamic segments, search params), and truly dynamic content (user-specific data, real-time updates). The client renders the app shell immediately, paints URL-specific data as it arrives, and streams dynamic content last.

This staged handoff eliminates the binary choice between instant-but-stale full prefetch and accurate-but-slow partial prefetch. The app shell is always safe to cache because it does not depend on user state or request timing. URL-specific data caches per route, so navigating between products on the same site reuses the shared shell and only fetches product-specific content. Dynamic content bypasses the cache entirely, guaranteeing freshness at the cost of a small delay.

// app/dashboard/[reportId]/page.tsx
import { Suspense } from 'react';

async function DashboardShell() {
  'use cache';
  return (
    <div className="dashboard-layout">
      <nav>Dashboard Navigation</nav>
      <aside>Filters</aside>
    </div>
  );
}

async function ReportData({ reportId }: { reportId: string }) {
  const data = await fetch(`/api/reports/${reportId}`).then(res => res.json());

  return <div>{JSON.stringify(data, null, 2)}</div>;
}

export default function ReportPage({ params }: { params: { reportId: string } }) {
  return (
    <>
      <DashboardShell />
      <Suspense fallback={<div>Loading report...</div>}>
        <ReportData reportId={params.reportId} />
      </Suspense>
    </>
  );
}

The diagram below shows the execution flow when partial prefetching is enabled. The prefetch extracts the app shell, the user clicks, the shell renders instantly, and the report data streams in as the server resolves the fetch.

The Instant Insights panel in the Next.js DevTools automatically detects slow navigations and suggests fixes. If a route lacks a loading shell, the panel shows a warning and generates a prompt that teaches AI agents how to add one. If a route has a loading shell but still feels slow, the panel identifies which components are blocking the critical path and suggests marking them with 'use cache'.

The official documentation (Next.js 16.3 release notes) describes Instant Insights as "a new devtool that automatically surfaces slow navigations." The panel runs in development mode only, monitoring every client-side transition and measuring the time from click to first paint. If the time exceeds a threshold (currently 300ms), the panel flags the navigation as slow and logs the component stack that blocked rendering.

This eliminates the guesswork that plagued prior versions. Developers no longer need to profile every link manually or instrument their code with performance marks. The DevTools highlight the problem, explain the root cause, and provide a concrete fix. All without leaving the browser.

Instant Insights panel in Next.js DevTools showing a slow navigation warning

The image shows the Instant Insights panel flagging a navigation to /dashboard/sales as slow because the route lacks a loading shell. The panel suggests adding a loading.tsx file or marking reusable components with 'use cache' to unlock instant navigation.

Debugging Slow Navigations: Finding the Real Culprit

Slow navigations in Next.js stem from four common causes: missing loading shells, expired router cache, blocking data fetches, and oversized prefetch payloads. Identifying the root cause requires inspecting the network tab, the React DevTools profiler, and the Next.js Instant Insights panel.

The network tab shows when prefetch requests fire and how long they take to complete. A prefetch that completes in 50ms but triggers a second identical request on click indicates a cache expiration problem. The user waited longer than the TTL, so the router cache invalidated the prefetched data and fetched it again.

The React DevTools profiler shows which components are blocking the critical path. If a navigation waits 2 seconds before painting anything, the profiler flame graph reveals which component is running slow. The usual suspects are data-fetching components that call fetch without Suspense boundaries, heavy computations in the render phase, and third-party libraries that block the main thread.

The Instant Insights panel ties these signals together by showing the full navigation trace. The panel logs the click event, the prefetch check, the cache hit or miss, the first paint, and the final layout shift. If the navigation is slow, the panel highlights the step that took the longest and suggests a fix.

The diagram shows the decision tree the router follows during navigation. If the cache is valid, the render happens immediately. If the cache expired, the navigation blocks while waiting for the server response. The gap between cache check and server response is where slowness accumulates.

Fixing slow navigations requires matching the solution to the root cause. If the cache expired, either shorten the time between prefetch and click (by prefetching on hover instead of on viewport entry) or extend the cache TTL by marking components with 'use cache'. If the navigation blocks on data fetches, wrap the slow components in Suspense boundaries and add a loading fallback. If the prefetch payload is too large, reduce it by setting prefetch={false} on low-priority links or splitting the route into smaller chunks.

The useLinkStatus hook (introduced in Next.js 16.2) provides immediate feedback during navigation. When a user clicks a link, the hook returns { pending: true } until the navigation completes, letting developers show a loading indicator without waiting for the server response.

'use client';

import { useLinkStatus } from 'next/link';

export default function NavigationIndicator() {
  const { pending } = useLinkStatus();

  if (!pending) return null;

  return (
    <div className="fixed top-0 left-0 right-0 h-1 bg-blue-500 animate-pulse" />
  );
}

The hook debounces fast navigations by adding a 100ms delay before returning pending: true. This prevents the loading indicator from flashing on screen for navigations that complete in under 100ms, reducing visual noise for instant transitions.

The official Next.js documentation (version 16.3) recommends combining useLinkStatus with CSS transitions to create a smooth loading experience: "You can 'debounce' the hint by adding an initial animation delay (e.g. 100ms) and starting as invisible (e.g. opacity: 0)." This gives the server time to respond before showing any feedback, avoiding flicker on fast networks.

For further reading on Next.js caching and performance, see the related posts Next.js 15 Caching Changes, Next.js App Router Layouts and Templates, and Next.js Caching Mental Model 2026.

Frequently Asked Questions

Why does my Next.js link prefetch but still feel slow when clicked?

The router cache expires prefetched data after 30 seconds for dynamic routes. If the user clicks after the TTL, the client fetches the route again even though the prefetch completed. Use 'use cache' to extend the TTL or reduce the delay between prefetch and click by prefetching on hover.

What is the difference between partial prefetch and full prefetch in App Router?

Partial prefetch loads the route down to the first Suspense boundary, sending the layout and loading shell but skipping page-specific data. Full prefetch loads the entire page including all data. Partial prefetch saves bandwidth but may feel slower if no loading shell exists. Use prefetch={true} to force full prefetch on critical links.

How does Next.js 16.3 partial prefetching change the default behavior?

In Next.js 16.3, enabling partialPrefetching: true makes prefetch="auto" send the app shell plus cached components instead of stopping at loading.tsx. This gives the client enough data to render an instant transition without requiring a separate loading file for every route.

When should I disable prefetching with prefetch={false}?

Disable prefetching for rarely-visited routes, infinite scroll lists, and links that appear in large quantities (like a product catalog with 1000 items). Prefetching wastes bandwidth if the user never clicks the link, and disabling it has no downside if the route is not performance-critical.

How do I debug which component is blocking a slow navigation?

Use the Instant Insights panel in the Next.js DevTools to identify slow navigations, then inspect the React DevTools profiler to see which component is blocking the critical path. The profiler flame graph shows render times per component, revealing bottlenecks like unwrapped data fetches or heavy computations in the render phase.

Making Next.js Navigations Feel Instant Without Breaking Dynamic Content

Next.js prefetching promises instant navigation but delivers slow transitions when the defaults collide with dynamic routes, expired caches, and missing loading shells. The confusion stems from partial prefetch stopping at Suspense boundaries, router cache expiration after 30 seconds, and the client blocking until the server responds with missing data.

Next.js 16.3 fixes this with partial prefetching, cache components, and Instant Insights. Developers mark reusable UI with 'use cache', and Next.js extracts it during prefetch, giving the client enough data to render an instant shell. Dynamic content streams in as the server resolves it, and the DevTools highlight any navigation that takes longer than 300ms, eliminating guesswork about which links need optimization.

Adopting the new primitives requires enabling two flags in next.config.ts and marking cached components with 'use cache'. The payoff is a server-rendered app that feels as responsive as a client-side SPA, with no stale data, no flicker, and no guesswork about when prefetches expire.

Next.js 16 `use cache` Directive: Granular Caching at the Function Level and What It Replaces

jsmanifest — Sat, 31 Oct 2026 06:06:39 +0000

Next.js 16 `use cache` Directive: Granular Caching at the Function Level and What It Replaces

Next.js 16 eliminates the framework's most confusing aspect: implicit caching. Previous versions cached fetch requests automatically, left developers guessing when route segments became static, and buried cache configuration inside fetch options. The new use cache directive makes every cache decision explicit. Developers mark what to cache, set expiration with cacheLife(), and invalidate with cacheTag().

The old model failed because developers could not predict cache behavior. A fetch call with no options might cache forever or not cache at all, depending on whether the route contained dynamic functions. Route segments became static or dynamic based on heuristics the compiler inferred from your code. Production bugs emerged when a component that worked dynamically in development suddenly rendered statically in production, serving stale data for hours.

Problem: implicit caching causes unpredictable cache behavior and stale data

Next.js 16 solves this with use cache. When you add the directive to a function or component, the framework caches its return value. When you call cacheLife('hours'), the cache expires in one hour. When you call cacheTag(['products']), you can invalidate that cache entry on demand. The mental model becomes: mark what you cache, state when it expires, name it for invalidation.

Solution: explicit use cache directive gives predictable control

This post covers what use cache replaces, how function-level and component-level caching work, migration patterns from unstable_cache, the cache hierarchy Next.js now uses, and production gotchas around cache storage.

Key Takeaways

use cache replaces unstable_cache, fetch cache options, and all implicit caching; every cache decision is now explicit.
You can cache at the function level (data fetching) or component level (entire UI trees), with arguments and closures becoming part of the cache key automatically.
cacheLife() sets expiration windows; cacheTag() enables on-demand invalidation; both pair with use cache to control freshness.
Cache storage defaults to in-memory per instance; use cache: remote moves entries to a shared durable handler for high hit rates.
Migration requires converting unstable_cache wrappers to use cache directives and replacing fetch next.revalidate with cacheLife() calls.

What `use cache` Replaces: unstable_cache, fetch Options, and Implicit Caching

use cache supersedes three caching mechanisms from Next.js 15 and earlier.

unstable_cache: developers wrapped functions in unstable_cache(fn, keyParts, options) to cache database queries or API calls. The wrapper returned a new function that memoized results. The name signaled instability; the API never graduated to stable. Next.js 16 removes it entirely.

fetch cache options: developers passed { next: { revalidate: 3600 } } to fetch calls to cache HTTP responses. The framework intercepted fetch, stored the response in a data cache, and served cached data until expiration. This worked only for fetch calls. Database queries and third-party SDK calls required unstable_cache.

Implicit route caching: Next.js analyzed route segments at build time. If a segment contained no dynamic functions (cookies, headers, searchParams), the compiler marked it static and prerendered it. If any child component called a dynamic function, the entire segment became dynamic. Developers could not see this decision; they inferred it from build output or production behavior.

All three mechanisms are gone. use cache handles every scenario.

Diagram showing old caching mechanisms replaced by use cache

The removal creates a single model. You mark cacheable operations with use cache, set expiration with cacheLife(), and invalidate with cacheTag(). The compiler generates cache keys from function arguments and captured closures. No wrapper functions, no fetch-specific options, no implicit heuristics.

This unification matters because developers now reason about caching the same way everywhere. A database query, a fetch call, and a React Server Component all use identical syntax. The cache key derivation follows the same rules. The expiration model applies uniformly.

How `use cache` Works: Function-Level and Component-Level Caching

The use cache directive applies to async functions and React Server Components. When Next.js encounters it, the framework serializes the function's return value into an RSC payload and stores that payload in a cache.

Function-level caching targets data operations. Add use cache to the top of an async function that fetches from a database, calls a third-party API, or performs expensive computation:

import { cacheLife } from 'next/cache';

export async function getProduct(id: string) {
  'use cache';
  cacheLife('hours');

  const product = await db.query(
    'SELECT * FROM products WHERE id = $1',
    [id]
  );

  return product;
}

The compiler generates a cache key from the function identity and its arguments. In this example, the key includes getProduct and the id value. Calling getProduct('123') creates one cache entry; calling getProduct('456') creates another. The framework does not cache the function itself; it caches the result for each unique set of arguments.

Component-level caching targets UI trees. Add use cache to an async component that renders JSX:

import { cacheLife } from 'next/cache';

export default async function ProductList() {
  'use cache';
  cacheLife('minutes');

  const products = await db.query('SELECT * FROM products');

  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

The framework caches the entire RSC payload for the component. The payload includes the rendered JSX, serialized props, and any data the component loaded. When Next.js renders the same component again within the cache window, it returns the cached payload without executing the component body.

Content image showing cache key generation and payload storage

How use cache generates keys and stores payloads

The cache key includes arguments and any values captured from parent scopes. If a component reads a variable from a closure, that variable becomes part of the key. This ensures different inputs produce separate cache entries.

Arguments and return values must be serializable. You cannot cache functions, class instances with methods, or objects containing Symbols. The framework serializes primitives, plain objects, arrays, and React elements. Attempting to cache non-serializable values throws a runtime error.

Components marked with use cache cannot directly call cookies(), headers(), or access searchParams. These APIs provide request-time data that varies per request. Calling them inside a cached function creates a contradiction: the cache expects stable inputs, but runtime APIs return dynamic values. If you need runtime data, pass it as an argument to the cached function from a non-cached parent component.

Using `cacheLife()` for Granular Cache Control

cacheLife() sets the expiration policy for a cached function. Without it, Next.js applies a default profile. The default provides basic time-based invalidation, but production apps need explicit control.

The function accepts a named profile or a custom configuration object. Next.js 16 ships with four built-in profiles:

Profile	Revalidate	Expire	Stale
`seconds`	15 seconds	15 seconds	1 minute
`minutes`	5 minutes	5 minutes	1 hour
`hours`	1 hour	1 hour	1 day
`days`	1 day	1 day	7 days

Revalidate determines when the cache entry becomes stale. After this window, Next.js marks the entry for refresh but continues serving the stale value while fetching a new one in the background.

Expire sets the hard limit. After this window, the cache entry becomes invalid. Requests cannot use it; Next.js must fetch fresh data synchronously.

Stale controls client-side caching. The browser keeps the RSC payload fresh for this duration when prefetching or navigating.

Use a built-in profile when the default windows fit your data freshness requirements:

import { cacheLife } from 'next/cache';

export async function getUser(id: string) {
  'use cache';
  cacheLife('hours');

  return await db.users.findUnique({ where: { id } });
}

Use a custom configuration when you need precise control:

import { cacheLife } from 'next/cache';

export async function getInventory(warehouseId: string) {
  'use cache';
  cacheLife({
    revalidate: 300,    // 5 minutes
    expire: 600,        // 10 minutes
    stale: 3600,        // 1 hour
  });

  return await inventoryApi.getStock(warehouseId);
}

The configuration accepts seconds as numbers. The example caches inventory for 5 minutes, expires it after 10 minutes, and allows the browser to use stale data for 1 hour during navigation.

Pairing cacheLife() with cacheTag() enables on-demand invalidation:

import { cacheLife, cacheTag } from 'next/cache';

export async function getProduct(id: string) {
  'use cache';
  cacheLife('hours');
  cacheTag('products', `product-${id}`);

  return await db.products.findUnique({ where: { id } });
}

When you call revalidateTag('products') from a Server Action, Next.js invalidates all cache entries tagged with products. The next request for any product executes the function and generates a fresh cache entry.

Migration Patterns: Converting Legacy Caching to `use cache`

Migrating from Next.js 15 caching requires three steps: remove unstable_cache wrappers, replace fetch cache options, and add explicit use cache directives.

Step 1: Remove unstable_cache wrappers

Old pattern with unstable_cache:

import { unstable_cache } from 'next/cache';

const getCachedUser = unstable_cache(
  async (id: string) => {
    return await db.users.findUnique({ where: { id } });
  },
  ['user'],
  { revalidate: 3600, tags: ['users'] }
);

export async function getUser(id: string) {
  return await getCachedUser(id);
}

New pattern with use cache:

import { cacheLife, cacheTag } from 'next/cache';

export async function getUser(id: string) {
  'use cache';
  cacheLife('hours');
  cacheTag('users');

  return await db.users.findUnique({ where: { id } });
}

The directive goes inside the function body. The cache key now derives automatically from the function identity and arguments. You do not specify key parts manually.

Step 2: Replace fetch cache options

Old pattern with fetch options:

export async function getProducts() {
  const response = await fetch('https://api.example.com/products', {
    next: { revalidate: 300, tags: ['products'] }
  });
  return response.json();
}

New pattern with use cache:

import { cacheLife, cacheTag } from 'next/cache';

export async function getProducts() {
  'use cache';
  cacheLife('minutes');
  cacheTag('products');

  const response = await fetch('https://api.example.com/products');
  return response.json();
}

The fetch call no longer carries cache options. The use cache directive controls caching for the entire function, including the fetch call and any subsequent processing.

Content image showing migration from old caching patterns to use cache

Step 3: Add explicit directives to previously implicit routes

Routes that relied on implicit static optimization need explicit use cache directives. If a page component performs data fetching that should cache, add the directive:

import { cacheLife } from 'next/cache';

export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  'use cache';
  cacheLife('hours');

  const { id } = await params;
  const product = await db.products.findUnique({ where: { id } });

  return <div>{product.name}</div>;
}

The migration flow moves all cache control to the function level. You see caching decisions in the code where they apply, not in build output or framework internals.

Migration flow from old caching patterns to use cache

`use cache` vs Data Cache vs Full Route Cache: Understanding the Cache Hierarchy

Next.js 16 maintains three cache layers: function-level cache (via use cache), prerendered HTML, and browser cache. Each serves a different purpose in the request lifecycle.

Function-level cache stores RSC payloads for individual functions and components. When you mark a function with use cache, Next.js caches its serialized return value. This cache applies during rendering. If a component calls a cached function multiple times in a single request, the framework returns the cached result after the first call.

Prerendered HTML stores complete pages generated at build time or during incremental static regeneration. When Next.js prerenders a page, it executes all cached functions, generates the RSC payload, renders HTML, and writes the HTML to disk. Subsequent requests serve the HTML directly without executing Server Components. The cacheLife expire window controls when the HTML becomes stale and triggers a background revalidation.

Browser cache stores RSC payloads the client receives during navigation or prefetching. When a user navigates to a new page, Next.js sends the RSC payload. The browser caches this payload according to the cacheLife stale window. During that window, navigating back to the page uses the cached payload without a server request.

Cache hierarchy showing function-level, HTML, and browser caches

These layers work together. A request hits the browser cache first. If the cached payload is stale, the browser requests from the server. The server checks for prerendered HTML. If the HTML is stale or missing, Next.js executes the page component. The component calls cached functions, which check the function-level cache. If a function's cached result is stale, the framework executes the function and updates the cache.

The distinction matters when you configure cacheLife. Setting revalidate to 5 minutes means the function-level cache refreshes every 5 minutes. Setting expire to 10 minutes means the prerendered HTML becomes invalid after 10 minutes. Setting stale to 1 hour means the browser uses its cached payload for 1 hour without checking the server.

Cache layer	Storage location	Invalidation trigger	Controlled by
Function-level	In-memory or remote handler	`revalidate` window or `revalidateTag()`	`cacheLife()` `revalidate`
Prerendered HTML	Disk or platform storage	`expire` window or deployment	`cacheLife()` `expire`
Browser	Client memory	`stale` window or user action	`cacheLife()` `stale`

The default cache handler stores function-level entries in memory per instance. This works for small apps but does not share cache across instances. For apps with multiple servers or serverless functions, use use cache: remote to store entries in a shared handler. The remote handler requires a network roundtrip for each cache hit, so it only pays off when the hit rate is high and the cached operation is expensive.

Production Gotchas: Cache Storage, Edge Runtime, and Common Mistakes

Production environments introduce cache storage constraints, edge runtime limitations, and developer mistakes that do not surface in local development.

Cache storage defaults to ephemeral in-memory per instance. When you deploy to a platform like Vercel, each serverless function instance maintains its own cache. Cache entries do not persist across cold starts. If an instance scales down and later scales up, the new instance starts with an empty cache. This differs from development, where next dev maintains a single long-running process with a persistent in-memory cache.

For durable shared caching, configure a cache handler in next.config.ts:

const nextConfig = {
  cacheHandlers: {
    default: {
      handler: './cache-handler.js',
    },
  },
};

export default nextConfig;

The cache handler must implement the Next.js cache handler interface. The official Redis handler provides a reference implementation. Using a remote cache introduces latency; each cache hit requires a network roundtrip to the cache store. Profile your cache hit rate before migrating. If the hit rate is low, the network overhead exceeds the benefit.

Edge runtime does not support all cache operations. Functions deployed to the edge can use use cache, but they cannot write to a durable cache handler that requires a persistent connection. The edge runtime allows only stateless HTTP requests. If your cached function must run at the edge, limit cache storage to the edge instance's memory. Cache entries do not persist across edge locations or instance restarts.

Common mistakes include caching non-serializable values, accessing runtime APIs inside cached functions, and misunderstanding cache key derivation.

Attempting to cache a class instance fails at runtime:

// This crashes when Next.js tries to serialize the cache entry
export async function getUserService(id: string) {
  'use cache';
  return new UserService(id);
}

The framework can only serialize plain objects, arrays, primitives, and React elements. Extract the data from the class instance and cache the data:

export async function getUserData(id: string) {
  'use cache';
  const service = new UserService(id);
  return await service.getData();
}

Accessing cookies() inside a cached function throws an error:

// This crashes because cookies() is a runtime API
export async function getSessionUser() {
  'use cache';
  const cookieStore = await cookies();
  const sessionId = cookieStore.get('session');
  return await db.sessions.findUnique({ where: { id: sessionId.value } });
}

Runtime APIs provide request-specific data. Caching request-specific data breaks the cache model. Move the runtime API call to a parent component and pass the value as an argument:

export async function Page() {
  const cookieStore = await cookies();
  const sessionId = cookieStore.get('session')?.value;

  if (!sessionId) {
    return <div>Not logged in</div>;
  }

  const user = await getCachedUser(sessionId);
  return <div>Hello {user.name}</div>;
}

async function getCachedUser(sessionId: string) {
  'use cache';
  cacheLife('minutes');

  const session = await db.sessions.findUnique({ 
    where: { id: sessionId },
    include: { user: true }
  });

  return session?.user;
}

The cached function receives sessionId as an argument. Different session IDs produce different cache entries. The cache key includes the session ID, so each user gets their own cached entry.

Production flow showing cache handler, edge limitations, and error paths

Cache key derivation includes function identity, arguments, and captured closures. If a closure captures a value from a parent scope, that value becomes part of the key. This can produce unintended cache misses if the captured value changes frequently:

export default async function ProductList({ category }: { category: string }) {
  const baseUrl = process.env.API_URL;

  // The cache key includes both category and baseUrl
  async function fetchProducts() {
    'use cache';
    const response = await fetch(`${baseUrl}/products?category=${category}`);
    return response.json();
  }

  return <div>{await fetchProducts()}</div>;
}

If API_URL changes between deployments, the cache key changes and all entries become invalid. For stable cache keys, pass environment variables as arguments or read them inside the cached function without capturing them from closures.

Frequently Asked Questions

When should you use `use cache: remote` instead of the default in-memory cache?

Use use cache: remote when your app runs on multiple serverless instances or containers and the cached operation is expensive enough to justify a network roundtrip. The remote cache shares entries across instances, but each cache hit requires fetching from the remote store. Profile your cache hit rate first; if it is below 80%, the network overhead likely exceeds the benefit.

Can you cache Server Actions with `use cache`?

Server Actions cannot use use cache directly because they are not idempotent operations; they mutate state rather than fetch data. You can pass Server Actions through cached components to Client Components without invoking them inside the cacheable function. The cached component treats the action as a serializable prop.

What happens when you call `revalidateTag()` with a tag that does not exist?

Calling revalidateTag() with a non-existent tag succeeds silently without invalidating anything. The framework does not track which tags exist; it only invalidates cache entries that match the tag. If no entries match, the call has no effect. This makes tag-based invalidation safe to call speculatively.

How does Next.js handle cache entries when you redeploy your app?

A new deployment generates a new build ID, which becomes part of the cache key for all use cache entries. When the build ID changes, all previous cache entries become inaccessible. This applies to both in-memory and remote caches. The new deployment starts with an empty cache, even if you use a durable cache handler.

Can you use `use cache` in Client Components?

Client Components cannot use use cache because they run in the browser, which has no server-side cache. The directive only works in Server Components and server-side async functions. If you need to cache data in a Client Component, fetch it in a Server Component, cache the Server Component with use cache, and pass the data as props.

Conclusion: Building a Mental Model for Next.js 16 Caching

The mental model for Next.js 16 caching reduces to three principles: mark what you cache, state when it expires, name it for invalidation. Every cache decision is explicit. No framework heuristics infer whether a route should cache. No fetch calls carry hidden cache options. No compiler analysis determines static versus dynamic rendering.

Add use cache to functions that fetch data or render UI. Call cacheLife() to set expiration windows. Call cacheTag() to enable on-demand invalidation. The compiler generates cache keys from function identity, arguments, and captured closures. Arguments and return values must be serializable. Runtime APIs like cookies() cannot be called inside cached functions.

Migration from Next.js 15 requires removing unstable_cache wrappers, replacing fetch cache options, and adding explicit directives. Production deployments need cache handler configuration for durable shared caching. Edge deployments limit cache to in-memory per instance. Cache entries do not persist across deployments because the build ID becomes part of the cache key.

The result is a caching model where developers control every aspect. You see caching decisions in the code where they apply. You reason about cache behavior the same way everywhere: functions, components, routes. You configure freshness requirements once, at the function level, rather than in multiple places with conflicting options. For teams managing complex data dependencies, this clarity eliminates an entire class of production bugs.

Next.js Turbopack Module Federation in 2026: Sharing Code Across Micro-Frontends Without Webpack

jsmanifest — Fri, 30 Oct 2026 12:09:46 +0000

Next.js Turbopack Module Federation in 2026: Sharing Code Across Micro-Frontends Without Webpack

Module federation in Next.js evolved from a webpack-specific pattern into a build-system-agnostic architecture problem. Organizations that built micro-frontend systems on webpack's Module Federation plugin now face a choice: rewrite for Turbopack's bundling model or adopt Next.js multi-zones with shared dependencies. The transition exposes assumptions about runtime module sharing that developers rarely questioned until the bundler changed.

Teams discover the issue when next dev --turbo replaces their development workflow. The webpack-based Module Federation configuration stops working because Turbopack does not expose webpack's container format or runtime APIs. A micro-frontend that loaded remote modules from sibling applications now fails at build time with "Cannot find module" errors. The application compiles when switching back to webpack with next dev --webpack, but production deployments target Turbopack for its speed improvements.

The solution requires rethinking module federation as a deployment pattern rather than a bundler feature. Next.js multi-zones provide the architectural foundation: separate applications that share a domain and coordinate routing. Shared dependencies move from runtime module containers to build-time package resolution. Remote modules become deployed zones that expose routes instead of JavaScript bundles. The host application routes requests to zone applications using rewrites, and zones handle their own bundling independently.

This architectural shift delivers better isolation and simpler deployment at the cost of runtime module sharing. Each zone bundles its own dependencies, which increases total JavaScript payload when zones duplicate packages. The tradeoff favors maintainability because zones deploy independently without coordinating dependency versions at runtime.

Key Takeaways

Turbopack does not support webpack's Module Federation plugin or container runtime APIs.
Next.js multi-zones replace module federation by deploying separate applications that share a domain through routing.
Shared dependencies resolve at build time through monorepo package references instead of runtime module containers.
Each zone bundles independently, which eliminates version coordination but increases total JavaScript size.
Production deployments use rewrites to route paths between zones while maintaining a single user-facing domain.

Understanding Module Federation in Next.js: The Current Webpack-Based Landscape

Module federation in webpack allows separate builds to share modules at runtime. A host application loads remote modules from deployed containers without including them in its own bundle. The ModuleFederationPlugin generates container entry points that expose selected modules and define shared dependencies. When the host application imports a federated module, webpack's runtime resolves the remote container URL and loads the module dynamically.

Next.js applications use this pattern by configuring webpack in next.config.js. The configuration defines exposed modules, shared dependencies, and remote container locations. A typical setup includes a host application that consumes modules from multiple remote applications.

// next.config.js for host application with webpack module federation
const { NextFederationPlugin } = require('@module-federation/nextjs-mf');

module.exports = {
  webpack(config, options) {
    config.plugins.push(
      new NextFederationPlugin({
        name: 'host',
        remotes: {
          remote1: `remote1@${process.env.REMOTE1_URL}/_next/static/chunks/remoteEntry.js`,
          remote2: `remote2@${process.env.REMOTE2_URL}/_next/static/chunks/remoteEntry.js`,
        },
        shared: {
          react: { singleton: true, requiredVersion: '^18.0.0' },
          'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
        },
      })
    );
    return config;
  },
};

The remote applications configure exposed modules that the host can import. Each remote builds a container that exports selected components and resolves shared dependencies according to the federation config.

// next.config.js for remote application
const { NextFederationPlugin } = require('@module-federation/nextjs-mf');

module.exports = {
  webpack(config, options) {
    config.plugins.push(
      new NextFederationPlugin({
        name: 'remote1',
        filename: 'static/chunks/remoteEntry.js',
        exposes: {
          './ProductCard': './components/ProductCard',
          './CheckoutButton': './components/CheckoutButton',
        },
        shared: {
          react: { singleton: true },
          'react-dom': { singleton: true },
        },
      })
    );
    return config;
  },
};

Runtime module sharing depends on webpack's container format and initialization sequence. The host application loads remote containers by injecting script tags or using dynamic imports. Webpack's runtime coordinates dependency resolution to ensure shared modules load exactly once. This works reliably when all applications use webpack with compatible container versions.

The webpack-specific implementation creates tight coupling between the bundler and the module federation architecture. Teams structure their micro-frontends around webpack's container format, which becomes a dependency that cannot be swapped without rewriting the entire system.

Module federation architecture diagram showing webpack containers

Turbopack's Architecture and What Changes for Module Federation

Turbopack replaces webpack as Next.js 16's default bundler. The architecture uses Rust-based incremental compilation with persistent caching, which delivers faster builds than webpack's JavaScript-based pipeline. Turbopack compiles only changed modules during development and caches compilation results to disk. Build times improve by 10x for large applications according to Vercel's benchmarks (Next.js 16 release notes, October 2026).

The bundler does not implement webpack's Module Federation plugin or container format. Turbopack's module system differs fundamentally from webpack's runtime architecture. Webpack generates container entry points that expose modules through a global object. Turbopack outputs ES modules with static import/export semantics that resolve at build time. There is no runtime container API to load federated modules dynamically.

Next.js 16 with Turbopack removes support for the webpack() configuration key in next.config.js. Applications that relied on webpack plugins for module federation no longer have access to the container plugin. The next dev and next build commands default to Turbopack, and the --webpack flag provides a temporary escape hatch for compatibility.

The architectural shift forces teams to reconsider how they structure micro-frontends. Runtime module federation assumed a bundler would coordinate module loading across deployed applications. Turbopack's design rejects that pattern in favor of build-time optimization and static analysis. Applications must adopt deployment-based federation where routing replaces runtime module containers.

Turbopack supports webpack loaders through a compatibility layer in the turbopack.rules configuration (Next.js Turbopack API reference, v16.1). This allows some webpack-based tooling to continue working, but does not extend to runtime plugins like Module Federation. The loader compatibility targets file transformations during compilation, not runtime module resolution.

The transition creates pressure to adopt alternative patterns that work with Turbopack's constraints. Next.js multi-zones become the primary approach for code sharing across micro-frontends. Each zone deploys as an independent application with its own Turbopack build. Zones coordinate through routing rather than module containers.

Implementing Module Federation with Next.js and Turbopack: Practical Setup

Multi-zones in Next.js provide the architectural replacement for webpack module federation. Each zone is a separate Next.js application that serves a subset of routes on a shared domain. The host application acts as the router, forwarding requests to zone applications based on URL paths. Zones deploy independently and bundle their dependencies without runtime coordination.

The setup requires configuring each zone with an assetPrefix to avoid static file conflicts. The host application defines rewrites that route paths to zone domains. A typical configuration includes three applications: a host that handles the root paths, and two zones for specialized features.

// next.config.ts for a zone application (e.g., product catalog)
import type { NextConfig } from 'next';

const config: NextConfig = {
  assetPrefix: '/catalog-static',
  async rewrites() {
    return {
      beforeFiles: [
        {
          source: '/catalog-static/_next/:path+',
          destination: '/_next/:path+',
        },
      ],
    };
  },
};

export default config;

The host application configures rewrites to forward zone paths to their deployed domains. This routes user requests to the correct application without exposing the zone URLs in the browser.

// next.config.ts for host application
import type { NextConfig } from 'next';

const config: NextConfig = {
  async rewrites() {
    return [
      {
        source: '/catalog',
        destination: `${process.env.CATALOG_ZONE_URL}/catalog`,
      },
      {
        source: '/catalog/:path+',
        destination: `${process.env.CATALOG_ZONE_URL}/catalog/:path+`,
      },
      {
        source: '/catalog-static/:path+',
        destination: `${process.env.CATALOG_ZONE_URL}/catalog-static/:path+`,
      },
      {
        source: '/checkout',
        destination: `${process.env.CHECKOUT_ZONE_URL}/checkout`,
      },
      {
        source: '/checkout/:path+',
        destination: `${process.env.CHECKOUT_ZONE_URL}/checkout/:path+`,
      },
      {
        source: '/checkout-static/:path+',
        destination: `${process.env.CHECKOUT_ZONE_URL}/checkout-static/:path+`,
      },
    ];
  },
};

export default config;

Shared code moves from runtime module federation to build-time package references. A monorepo structure with workspaces allows zones to import shared components and utilities as npm packages. Each zone includes shared packages as dependencies and Turbopack bundles them at build time.

// package.json for zone application in monorepo
{
  "name": "@company/catalog-zone",
  "dependencies": {
    "@company/ui-components": "workspace:*",
    "@company/auth-utils": "workspace:*",
    "next": "16.1.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  }
}

Zones import shared components using standard ES module imports. Turbopack resolves workspace packages during compilation and includes them in each zone's bundle.

// app/catalog/page.tsx in catalog zone
import { ProductCard } from '@company/ui-components';
import { useAuth } from '@company/auth-utils';

export default function CatalogPage() {
  const { user } = useAuth();

  return (
    <div>
      <h1>Product Catalog</h1>
      {user && <p>Welcome, {user.name}</p>}
      <ProductCard
        title="Example Product"
        price={29.99}
        imageUrl="/products/example.jpg"
      />
    </div>
  );
}

This setup eliminates runtime module containers and version coordination. Each zone bundles its dependencies independently, which increases total payload size when zones duplicate packages. The tradeoff favors deployment independence and simpler dependency management.

Multi-zone architecture with shared packages

Remote Module Consumption Patterns: Host and Remote App Configuration

Remote module consumption in multi-zones requires explicit routing configuration instead of dynamic imports. The host application cannot load zone components directly because zones deploy as separate Next.js applications. Navigation between zones performs hard page loads that unload the current zone's resources and load the new zone.

Zones expose routes rather than component exports. A zone serves pages at specific paths, and the host application routes users to those paths through rewrites or standard links. The browser treats navigation to a zone as a navigation to a different part of the same domain.

// app/page.tsx in host application
import Link from 'next/link';

export default function HomePage() {
  return (
    <div>
      <h1>Welcome</h1>
      <nav>
        <Link href="/catalog">Browse Products</Link>
        <Link href="/checkout">Checkout</Link>
      </nav>
    </div>
  );
}

Clicking the link to /catalog triggers a hard navigation to the catalog zone. The host application's rewrite configuration forwards the request to the catalog zone's domain, and the browser loads the catalog zone's JavaScript bundle. This differs from webpack module federation where a federated component could render within the host's page without a navigation.

Shared data patterns require server-side coordination or external state. Zones cannot share React state or context across zone boundaries because each zone runs its own React root. Authentication tokens, user preferences, and cart data must persist in cookies, localStorage, or a backend API that all zones can access.

// lib/auth.ts shared package used by all zones
import { cookies } from 'next/headers';

export async function getUser() {
  const cookieStore = await cookies();
  const token = cookieStore.get('auth_token');

  if (!token) {
    return null;
  }

  const response = await fetch(`${process.env.API_URL}/user`, {
    headers: { Authorization: `Bearer ${token.value}` },
  });

  return response.ok ? response.json() : null;
}

Each zone calls getUser() independently to fetch user data from the backend. The function lives in a shared package that all zones import, but execution happens separately in each zone's server runtime.

Soft navigation within a zone uses Next.js's Link component normally. Navigating between pages in the same zone performs client-side routing without reloading the application. Hard navigation only occurs when crossing zone boundaries.

The pattern forces explicit boundaries between micro-frontends. Zones must define clear responsibilities and minimize cross-zone dependencies. A catalog zone handles product browsing and search. A checkout zone manages cart and payment. The host application provides navigation and shared layout elements.

Performance Comparison: Webpack Module Federation vs Turbopack-Compatible Approaches

Aspect	Webpack Module Federation	Turbopack Multi-Zones
Build time	60-120 seconds for host + remotes	5-15 seconds per zone (parallel builds)
Initial page load	180-250 KB (host + federation runtime)	120-180 KB per zone (no federation overhead)
Subsequent zone navigation	80-120 KB (remote container + modules)	120-180 KB (full page with new bundle)
Shared dependency handling	Runtime version negotiation	Build-time resolution (duplicated across zones)
Hot module reload	2-5 seconds (webpack HMR)	50-500 milliseconds (Turbopack incremental)
Deploy coordination	Must align dependency versions across remotes	Independent zone deploys

Webpack module federation delivers smaller initial payloads when multiple remotes share dependencies. The federation runtime loads React once and reuses it across all federated components. Each remote module adds only its unique code to the total JavaScript size. This optimization matters when a host application loads five or more remote modules from different teams.

Turbopack multi-zones duplicate shared dependencies across zone bundles. If three zones each use React, React ships three times. The duplication increases total JavaScript by 40-60 KB per additional zone for typical React applications. The cost compounds with additional shared dependencies like state management libraries or UI frameworks.

Build performance favors Turbopack by a significant margin. Each zone builds independently in parallel, and Turbopack's incremental compilation completes in seconds. Webpack module federation requires coordinating builds across all federated applications and waiting for the slowest remote to finish. Large organizations with 10-15 micro-frontends see build pipelines complete 5-10x faster with multi-zones.

Development experience improves with Turbopack's hot module reload speed. Changes to zone code reflect in the browser within 500 milliseconds. Webpack HMR takes 2-5 seconds for equivalent updates in federated applications. The difference compounds during feature development where developers make hundreds of small changes per day.

The navigation model trades client-side routing for simpler architecture. Webpack module federation loads remote modules without page navigation, which feels faster to users moving between micro-frontends. Multi-zones perform hard navigations that reload the entire page. The perceived slowdown disappears for applications where zones represent distinct user workflows with infrequent transitions.

Version coordination becomes simpler with multi-zones. Each zone deploys independently with its own dependency versions. Breaking changes in shared packages affect only the zones that have not upgraded. Webpack module federation requires all remotes to coordinate React and shared library versions to avoid runtime conflicts. The coordination overhead grows with team count.

Production Patterns: Shared Dependencies, Versioning, and Error Boundaries

Shared dependencies in multi-zones require build-time coordination through package versioning. Monorepo workspaces allow zones to depend on shared packages that reference the same version. Breaking changes in shared code require updating all consuming zones before deployment.

// packages/ui-components/package.json
{
  "name": "@company/ui-components",
  "version": "3.2.0",
  "peerDependencies": {
    "react": "^18.3.0",
    "react-dom": "^18.3.0"
  }
}

Zones specify workspace dependencies using the workspace:* protocol. This ensures all zones use the same version of shared packages without duplicating package code in the repository.

// apps/catalog-zone/package.json
{
  "dependencies": {
    "@company/ui-components": "workspace:*",
    "@company/analytics": "workspace:*"
  }
}

Version conflicts surface at build time rather than runtime. If a zone attempts to import an incompatible shared package version, the build fails with a clear error message. This prevents the subtle runtime failures that occur with webpack module federation when remotes load conflicting dependency versions.

Error boundaries protect against zone failures at the routing level. If a zone crashes or fails to load, the host application can display a fallback UI instead of a broken page. This requires implementing error handling in the zone's root layout.

// app/layout.tsx in zone application
import { ErrorBoundary } from '@company/ui-components';

export default function ZoneLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <ErrorBoundary
      fallback={
        <div>
          <h1>Something went wrong</h1>
          <p>We are working to fix this issue.</p>
          <a href="/">Return to home</a>
        </div>
      }
    >
      {children}
    </ErrorBoundary>
  );
}

The error boundary catches React errors within the zone and renders the fallback UI. This prevents a crashed zone from breaking the entire application. Users can navigate back to the host or other zones even when one zone fails.

Network errors during zone navigation require server-side fallbacks. If a zone's server becomes unavailable, the host application's rewrite returns a 502 error. Next.js middleware can intercept these errors and redirect to a maintenance page.

// middleware.ts in host application
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export async function middleware(request: NextRequest) {
  const zonePaths = ['/catalog', '/checkout'];
  const isZonePath = zonePaths.some(path => 
    request.nextUrl.pathname.startsWith(path)
  );

  if (isZonePath) {
    try {
      const response = await fetch(request.url, {
        method: request.method,
        headers: request.headers,
      });

      if (!response.ok) {
        return NextResponse.redirect(new URL('/maintenance', request.url));
      }

      return response;
    } catch (error) {
      return NextResponse.redirect(new URL('/maintenance', request.url));
    }
  }

  return NextResponse.next();
}

Observability for multi-zones requires tracing requests across zone boundaries. Each zone should emit structured logs that include a request ID propagated through rewrites. The host application generates the request ID and passes it to zones via headers.

// middleware.ts in host application
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { randomUUID } from 'crypto';

export function middleware(request: NextRequest) {
  const requestId = randomUUID();
  const requestHeaders = new Headers(request.headers);
  requestHeaders.set('x-request-id', requestId);

  return NextResponse.next({
    request: { headers: requestHeaders },
  });
}

Zones extract the request ID from headers and include it in log output. This allows correlating errors across zone boundaries when debugging production issues.

Dependency optimization reduces bundle duplication when multiple zones share heavy libraries. The optimizePackageImports option in next.config.ts tells Turbopack to tree-shake package imports, which eliminates unused code from bundles (Next.js package bundling guide, v16.1).

// next.config.ts for zone application
import type { NextConfig } from 'next';

const config: NextConfig = {
  experimental: {
    optimizePackageImports: ['@mui/material', 'lodash', 'date-fns'],
  },
};

export default config;

This configuration reduces bundle size by 20-40 KB for zones that import only a subset of package exports. The optimization applies per zone, which means each zone still bundles its own copy of shared packages but with only the required code.

Server actions require explicit origin allowlists when zones share a domain. Next.js validates the origin header for server action requests to prevent CSRF attacks. The host domain must appear in each zone's allowedOrigins configuration (Next.js server actions configuration, v16.0).

// next.config.ts for zone application
import type { NextConfig } from 'next';

const config: NextConfig = {
  experimental: {
    serverActions: {
      allowedOrigins: ['example.com', 'www.example.com'],
    },
  },
};

export default config;

Without this configuration, server actions in zones fail with CSRF errors when the zone serves requests proxied through the host domain.

Frequently Asked Questions

Can Turbopack load webpack module federation containers?

No. Turbopack does not implement webpack's container format or runtime APIs. Applications using webpack module federation must either continue using webpack with the --webpack flag or migrate to multi-zones.

How do multi-zones handle shared React state?

Zones cannot share React state directly because each zone runs its own React root. Shared state requires external storage like cookies, localStorage, or a backend API that all zones access.

Do multi-zones work with third-party deployed micro-frontends?

Yes. Zones can route to any deployed application using rewrites. The remote application does not need to be a Next.js zone as long as it serves content at the routed path.

What happens when a zone deployment fails?

Failed zone deployments do not affect other zones. The host application continues serving its routes and other zones. Users navigating to the failed zone see errors only when accessing that zone's paths.

Can zones share Next.js middleware?

No. Each zone executes its own middleware independently. Shared middleware logic must be extracted to a package that zones import and execute separately.

Conclusion: The Future of Micro-Frontends in Next.js

Multi-zones replace runtime module federation with deployment-based architecture. The pattern aligns with Turbopack's build-time optimization model and removes the complexity of runtime module coordination. Organizations gain faster builds, independent zone deployments, and simpler dependency management at the cost of larger total JavaScript payloads.

The architectural shift requires rethinking micro-frontend boundaries. Zones work best when they represent distinct user workflows with infrequent navigation between them. Applications that require frequent component-level code sharing across teams may find the hard navigation overhead expensive. Those cases benefit from extracting shared code to packages rather than attempting runtime module sharing.

Turbopack's adoption as Next.js's default bundler makes multi-zones the standard approach for micro-frontends in the Next.js ecosystem. The webpack-based module federation pattern remains available through the --webpack flag but receives no optimization attention from the framework. Teams building new micro-frontend architectures should design around multi-zones from the start.

For further exploration of Next.js architectural patterns, see related posts on Next.js 15 caching changes, Next.js 16 form component progressive enhancement, and Next.js 16 instrumentation stable.

Claude Code Structured Output Mode in 2026: Forcing JSON Responses From Subagents and Validating Them With Zod

jsmanifest — Thu, 29 Oct 2026 12:06:22 +0000

Claude Code Structured Output Mode in 2026: Forcing JSON Responses From Subagents and Validating Them With Zod

Claude Code Structured Output Mode in 2026: Forcing JSON Responses From Subagents and Validating Them With Zod

Subagents in Claude Code return unstructured text by default. When a lead agent spawns five parallel subagents to extract metadata from API endpoints, the lead receives five prose summaries. Parsing those summaries for the actual data means regex patterns, fallback heuristics, and silent failures when a subagent changes its response format mid-conversation.

Structured output mode forces subagents to return validated JSON that matches a schema you define. The lead receives the exact shape it expects, and Zod validates every field before the result reaches the lead's context. No parsing, no silent failures.

This post shows how to pass outputFormat to a query() session you run as a worker, validate structured output with Zod as soon as it lands on the result message, and compose JSON schemas for multi-agent workflows that demand reliability. Examples run on Claude Code SDK v0.3.301 with Claude Fable 5.1 (claude-fable-5-1), which dropped support for tool_choice types any and tool in the September 1, 2026 release. The structured output and strict tool use patterns here replace the removed tool-choice guarantees.

Claude Code structured output validation workflow

Key Takeaways

Structured output mode forces subagents to return validated JSON matching a schema, eliminating regex parsing and silent format drift.
Pass outputFormat: { type: "json_schema", schema: zodSchema } to query() to constrain an agent session's final result.
Zod schemas generate JSON Schema with .toJSONSchema(schema, { target: "draft-7" }) and provide TypeScript types through inference.
The SDK wraps the result in a synthetic StructuredOutput tool call, validates it against your schema, and retries automatically, so your own code only ever sees validated JSON on message.structured_output or a terminal retry error.
On validation failure, the SDK re-prompts the agent with the mismatch up to the retry limit; only error_max_structured_output_retries reaches your result-handling code if every attempt fails.

Understanding Claude Code Structured Output Mode: The Synthetic Tool Pattern

Structured output mode wraps the subagent's final response in a synthetic tool call. The SDK generates a tool definition from the schema you provide, instructs the model to call that tool with the result, validates the call against the schema, and surfaces the validated JSON to the lead. The subagent still uses any tools it needs during execution (Grep, Bash, file operations), but the final turn must conform to the structure you defined.

The schema is a JSON Schema object. Zod schemas convert to JSON Schema with zodToJsonSchema() from the zod-to-json-schema package. The SDK supports standard JSON Schema features: object, array, string, number, boolean, null, enum, const, required, nested objects, and $ref definitions. The format keyword (like "format": "email") is accepted as an annotation but not enforced. Before SDK v2.1.205, invalid schemas were silently ignored and the subagent returned unstructured text. After v2.1.205, an invalid schema fails the run at startup with an error naming the problem.

The agent attempts the synthetic tool call up to the retry limit (default 3). If validation fails on every attempt, the result becomes an error of type error_max_structured_output_retries. Your code sees that error directly on the result message's subtype, so check it before trusting structured_output.

Forcing JSON Responses From Subagents: Passing outputFormat to a query() Session

A worker session accepts outputFormat in the same shape as any other query() call. Define a Zod schema, convert it to JSON Schema, and pass it to query(). The example below spawns a query() session to extract repository metadata and return it as a typed object:

import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";
import { query } from "@anthropic-ai/claude-agent-sdk";

const repoMetadataSchema = z.object({
  name: z.string().describe("Repository name"),
  primaryLanguage: z.string().describe("Primary programming language"),
  stars: z.number().int().nonnegative().describe("Star count"),
  openIssues: z.number().int().nonnegative().describe("Open issue count"),
  lastCommitDate: z.string().describe("ISO 8601 date of last commit")
});

type RepoMetadata = z.infer<typeof repoMetadataSchema>;

const jsonSchema = zodToJsonSchema(repoMetadataSchema, { 
  target: "draft-7" 
});

async function analyzeRepository(repoPath: string): Promise<RepoMetadata> {
  const messages = [];

  for await (const message of query({
    prompt: `Analyze the repository at ${repoPath} and extract metadata`,
    options: {
      outputFormat: {
        type: "json_schema",
        schema: jsonSchema
      }
    }
  })) {
    messages.push(message);

    if (message.type === "result" && message.subtype === "success") {
      if (!message.structured_output) {
        throw new Error("Expected structured output but received none");
      }
      return message.structured_output as RepoMetadata;
    }

    if (message.type === "result" && message.subtype === "error") {
      throw new Error(`Subagent failed: ${message.error}`);
    }
  }

  throw new Error("Subagent completed without result");
}

The subagent uses Bash to run git log, Grep to search for language indicators, and Read to examine configuration files. The final result matches the schema or triggers a retry. The lead receives a typed RepoMetadata object with no parsing layer.

Optional fields follow Zod's .optional() pattern. The JSON Schema includes them in properties but omits them from required. When the subagent cannot populate an optional field (like an author name for a file with no git history), it omits the key from the synthetic tool call, and TypeScript infers the field as string | undefined:

const todoSchema = z.object({
  text: z.string(),
  file: z.string(),
  line: z.number().int().positive(),
  author: z.string().optional(),
  date: z.string().optional()
});

type Todo = z.infer<typeof todoSchema>;

The author and date keys appear in the JSON Schema with no required constraint. The subagent populates them when git blame data exists and omits them otherwise. Downstream code checks todo.author !== undefined before using the value.

Validating Structured Output With Zod: From JSON Schema to Runtime Type Safety

Zod provides both the JSON Schema for the SDK and the runtime validator for the result. The parse() method throws on validation failure. The safeParse() method returns { success: true, data: T } or { success: false, error: ZodError }. Production code typically calls safeParse() right after reading message.structured_output in the result-handling loop, as a second layer of runtime checks (like date-format refinements) on top of the SDK's own schema validation.

The schema from the previous section generates this JSON Schema, which the SDK passes to the model:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Repository name"
    },
    "primaryLanguage": {
      "type": "string",
      "description": "Primary programming language"
    },
    "stars": {
      "type": "integer",
      "minimum": 0,
      "description": "Star count"
    },
    "openIssues": {
      "type": "integer",
      "minimum": 0,
      "description": "Open issue count"
    },
    "lastCommitDate": {
      "type": "string",
      "description": "ISO 8601 date of last commit"
    }
  },
  "required": ["name", "primaryLanguage", "stars", "openIssues", "lastCommitDate"],
  "additionalProperties": false
}

Runtime validation applies the same constraints. Zod checks that stars is a nonnegative integer and lastCommitDate is a string. Custom refinements enforce stricter rules:

const repoMetadataSchema = z.object({
  name: z.string().min(1),
  primaryLanguage: z.string().min(1),
  stars: z.number().int().nonnegative(),
  openIssues: z.number().int().nonnegative(),
  lastCommitDate: z.string().refine(
    (val) => !isNaN(Date.parse(val)),
    { message: "Must be a valid ISO 8601 date" }
  )
});

The refinement on lastCommitDate rejects malformed date strings like "2026-13-01". The SDK's validation catches basic type mismatches, and Zod's refinement catches semantic errors. When a subagent returns "2026-13-01", the synthetic tool call fails validation, the SDK retries, and the subagent eventually corrects itself or exhausts retries.

Zod validation pipeline from JSON Schema to runtime type checking

Zod v4 (released in late 2025) changed the refinement API and the shape of ZodError. The zodToJsonSchema() function supports both Zod v3 and v4. Projects upgrading to Zod v4 must update error-handling code that inspects error.issues directly, because the issues array structure changed. The JSON Schema output remains compatible across versions.

Result-Loop Validation: Checking Output Before Your Application Trusts It

The SDK's own validation only checks the synthetic StructuredOutput tool call against your JSON Schema; it does not run your Zod refinements. Those run in your code, in the for await loop that consumes the result message, right after you read message.structured_output and before anything downstream touches it.

The example below validates repository metadata as soon as the result message arrives, and treats a refinement failure as a terminal error for that call rather than a mid-session retry:

import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";
import { query } from "@anthropic-ai/claude-agent-sdk";

const repoMetadataSchema = z.object({
  name: z.string().min(1),
  primaryLanguage: z.string().min(1),
  stars: z.number().int().nonnegative(),
  openIssues: z.number().int().nonnegative(),
  lastCommitDate: z.string().refine(
    (val) => !isNaN(Date.parse(val)),
    { message: "Must be a valid ISO 8601 date" }
  )
});

type RepoMetadata = z.infer<typeof repoMetadataSchema>;

const jsonSchema = zodToJsonSchema(repoMetadataSchema, { 
  target: "draft-7" 
});

async function analyzeWithValidation(repoPath: string): Promise<RepoMetadata> {
  for await (const message of query({
    prompt: `Analyze the repository at ${repoPath} and extract metadata`,
    options: {
      outputFormat: {
        type: "json_schema",
        schema: jsonSchema
      }
    }
  })) {
    if (message.type === "result" && message.subtype === "success" && message.structured_output) {
      const result = repoMetadataSchema.safeParse(message.structured_output);

      if (!result.success) {
        const errors = result.error.issues
          .map(issue => `${issue.path.join(".")}: ${issue.message}`)
          .join("; ");

        throw new Error(`Validation failed: ${errors}`);
      }

      return result.data;
    }

    if (message.type === "result" && message.subtype === "error_max_structured_output_retries") {
      throw new Error("SDK could not produce output matching the schema");
    }
  }

  throw new Error("Query completed without result");
}

The SDK's schema validation and retry loop already ran by the time this message reaches your code, so message.structured_output is guaranteed to match your JSON Schema's basic types. The safeParse() call here applies the stricter runtime refinements Zod carries (like the ISO date check) that never reached the SDK, because only the generated JSON Schema was passed to outputFormat.

The pattern scales to multiple workers. A caller spawning ten parallel query() sessions runs the same validation on each result message independently, and only valid results get collected into the caller's own aggregate.

Error Handling: What Happens When Structured Output Validation Fails

The SDK retries failed validation up to the retry limit (default 3). After the limit, the result message's subtype becomes error_max_structured_output_retries. Your result-handling code sees this directly on the message; there is no hook step in between. Production workflows typically branch on subtype right there and log the failure for debugging.

The retry loop is automatic. The SDK provides feedback to the model after each failed attempt, describing the validation error and the expected schema. The model corrects its response and tries again. When retries exhaust without a valid result, the error surfaces. The example below catches the error in the main query loop:

async function analyzeWithErrorHandling(repoPath: string): Promise<RepoMetadata | null> {
  try {
    for await (const message of query({
      prompt: `Analyze the repository at ${repoPath} and extract metadata`,
      options: {
        outputFormat: {
          type: "json_schema",
          schema: jsonSchema
        }
      }
    })) {
      if (message.type === "result" && message.subtype === "success" && message.structured_output) {
        const result = repoMetadataSchema.safeParse(message.structured_output);

        if (!result.success) {
          console.error("Validation failed:", result.error.issues);
          return null;
        }

        return result.data;
      }

      if (message.type === "result" && message.subtype === "error_max_structured_output_retries") {
        console.error("SDK retries exhausted without valid output");
        return null;
      }
    }
  } catch (error) {
    console.error("Query threw:", error);
    return null;
  }

  return null;
}

A result can also come back with subtype: "success" but no structured_output at all, for example when the run completes without the agent producing one. Treat that case as a failure too, the same as the explicit retry-exhaustion subtype.

Some validation failures are unrecoverable. When the schema expects an integer and the agent's tools can only return a string, the SDK's own retries will exhaust without progress. Production systems often include a fallback path: if structured output fails, the caller retries with a simpler schema or a prose-based extraction prompt.

Production Patterns: Composing Subagent JSON Schemas for Multi-Agent Workflows

Multi-agent workflows compose schemas hierarchically. A lead spawns a subagent to analyze a repository, and that subagent spawns child subagents to analyze individual files. Each level defines its own schema, and the parent's schema includes the child's schema as a nested object or array.

The repository metadata schema from earlier examples extends to include an array of file analyses:

const fileAnalysisSchema = z.object({
  path: z.string(),
  language: z.string(),
  lines: z.number().int().positive(),
  complexity: z.number().int().nonnegative(),
  lastModified: z.string()
});

const repoAnalysisSchema = z.object({
  name: z.string().min(1),
  primaryLanguage: z.string().min(1),
  stars: z.number().int().nonnegative(),
  openIssues: z.number().int().nonnegative(),
  lastCommitDate: z.string(),
  files: z.array(fileAnalysisSchema)
});

type RepoAnalysis = z.infer<typeof repoAnalysisSchema>;

The lead spawns a subagent with outputFormat set to the repoAnalysisSchema. That subagent spawns child subagents to analyze individual files, each with outputFormat set to fileAnalysisSchema. The lead receives a single RepoAnalysis object with fully typed nested data. Validation at each level guarantees that every file analysis conforms to fileAnalysisSchema and the repository analysis conforms to repoAnalysisSchema.

The composition pattern scales to arbitrary nesting depth. A subagent analyzing a file might spawn subagents to analyze functions, and those subagents return function-level schemas. The top-level lead receives a deeply nested typed object with no manual assembly.

Parallel subagents often return arrays. A lead spawning ten subagents to analyze ten repositories defines a schema like this:

const batchAnalysisSchema = z.object({
  repositories: z.array(repoAnalysisSchema),
  totalStars: z.number().int().nonnegative(),
  mostActiveRepo: z.string()
});

The lead spawns ten child subagents, each returning a RepoAnalysis object. The lead collects the results, computes totalStars and mostActiveRepo, and returns a batchAnalysisSchema-shaped object. The parent that spawned the lead receives a single typed payload summarizing ten repositories.

Comparison of schema composition strategies:

Strategy	Use case	Validation overhead	Type safety
Flat schema	Single subagent, simple output	Low (one validation)	Full (single-level inference)
Nested schema	Hierarchical analysis (repo → files)	Medium (validation per level)	Full (deep inference with nested types)
Array schema	Parallel subagents returning same shape	High (validation per element)	Full (array element type inferred)
Discriminated union	Subagents returning different shapes	Medium (one validation, branching types)	Full (union type inferred)

Discriminated unions handle cases where subagents return different shapes based on runtime conditions. A subagent analyzing a file might return different schemas for source files versus configuration files:

const sourceFileSchema = z.object({
  type: z.literal("source"),
  path: z.string(),
  language: z.string(),
  functions: z.array(z.string())
});

const configFileSchema = z.object({
  type: z.literal("config"),
  path: z.string(),
  format: z.string(),
  keys: z.array(z.string())
});

const fileSchema = z.discriminatedUnion("type", [
  sourceFileSchema,
  configFileSchema
]);

type FileAnalysis = z.infer<typeof fileSchema>;

The subagent returns a type field that determines the shape. TypeScript narrows the type based on the discriminant:

function processFile(file: FileAnalysis) {
  if (file.type === "source") {
    console.log(`Functions: ${file.functions.join(", ")}`);
  } else {
    console.log(`Config keys: ${file.keys.join(", ")}`);
  }
}

This pattern is common in workflows where a subagent inspects a file and decides the appropriate analysis strategy at runtime. The lead receives a single schema that accommodates both outcomes, and TypeScript enforces exhaustive handling of the union.

Frequently Asked Questions

What happens if a query() session exhausts retries without producing valid structured output?

The SDK yields a result message with type: "result" and subtype: "error_max_structured_output_retries". Your result-handling code reads this subtype directly off the message and can branch into a fallback strategy right there; there is no hook in between.

Can structured output mode work with custom tools defined in the agent session?

Structured output mode wraps the final result in a synthetic tool call, separate from any custom tools the agent uses during execution. The agent can call custom tools (like a database query tool) as many times as needed, then return the final result via the synthetic tool. Custom tools do not need to match the output schema; only the final result does.

How do I migrate from regex parsing to structured output mode in an existing workflow?

Replace the prose prompt (like "return the data as JSON") with an outputFormat option. Define a Zod schema matching the shape your regex currently extracts, convert it to JSON Schema with zodToJsonSchema(), and pass it to query(). Remove the regex parsing code and read message.structured_output directly. Add a safeParse() check in your result-handling loop to catch any edge cases your regex missed before trusting the output.

Does structured output mode increase latency compared to unstructured responses?

Structured output mode adds one synthetic tool call at the end of the session's execution. Latency increases by the time to generate and validate that call. Retries on validation failure add incremental latency, but the retry loop is automatic and parallel across multiple sessions, so ten parallel workers with retries often complete faster than sequential prose parsing.

Can I use Zod v4 refinements with the Claude Code SDK?

Zod v4 refinements work with the SDK because zodToJsonSchema() supports both Zod v3 and v4. The refinement runs at runtime in your own result-handling code, not inside the SDK's validation. The SDK validates basic types against the JSON Schema, and Zod's safeParse() applies refinements like date format checks or custom business logic.

Conclusion: Building Reliable Agent Pipelines With Structured Output and Zod

Structured output mode in Claude Code eliminates regex parsing from multi-agent workflows. Agent sessions return validated JSON matching schemas you define, and Zod enforces type safety from the schema definition through runtime validation. Your result-handling loop reads message.structured_output off the result message and applies Zod's runtime refinements before anything downstream touches it, so invalid payloads never propagate silently. Production pipelines compose schemas hierarchically, spawning worker sessions that return typed objects fitting directly into the parent's schema. Related patterns for cost control and CI integration appear in Claude Code cost control for production workflows and CI agentic review with auto-fix. Compare the 2026 tooling landscape in Claude Code versus Cursor and Windsurf.

TypeScript Tuples in 2026: Labeled Elements, Variadic Spreads, and When a Tuple Beats an Interface

jsmanifest — Wed, 28 Oct 2026 06:06:15 +0000

TypeScript Tuples in 2026: Labeled Elements, Variadic Spreads, and When a Tuple Beats an Interface

Most TypeScript engineers reach for interfaces when they need structured data. That reflex breaks when an API returns coordinates, a useState hook returns [value, setter], or middleware needs to compose through a chain of handlers. Arrays do not enforce length or per-index types. Interfaces force named property access when destructuring is cleaner.

The type system accepts [string, number] as valid but offers no hints at the call site. Engineers write result[0] with no indication whether zero holds a user ID or an error message. The compiler stays silent when position assumptions drift.

Labeled tuple elements fix this. The syntax [id: string, count: number] preserves position semantics while surfacing parameter names in autocomplete and signature help. Variadic tuple types compose middleware signatures. Readonly tuples prevent mutation.

The mechanics have been in TypeScript since 4.0 (August 2020) with variadic tuples and 4.2 (February 2021) with leading/trailing rest elements, per the TypeScript 4.0 release notes and 4.2 release notes. By 2026 the patterns are stable. What remains is knowing when a tuple wins over an interface and when adding a fourth element means you picked the wrong tool.

Key Takeaways

Labeled tuple elements [id: string, count: number] surface parameter names in IDE autocomplete and signature help with zero runtime cost.
Variadic tuple types enable type-safe function composition and middleware pipelines by spreading rest parameters into tuple positions.
Tuples beat interfaces when destructuring order matters, when position carries semantic meaning, or when returning small fixed-length collections from functions.
Readonly tuples and as const assertions prevent runtime mutations and lock down literal types at compile time.
Long tuples (more than 4 elements) sacrifice readability; switch to an interface when named properties clarify intent better than position.

What Makes TypeScript Tuples Different From Arrays in 2026

A tuple enforces fixed length and per-index types; an array enforces element homogeneity across unknown length.

An array of numbers number[] accepts zero elements or a million. The type system cannot tell you what lives at index three. A tuple [string, number, boolean] must hold exactly three elements with those exact types at those exact positions.

// Array: homogeneous, variable length
const scores: number[] = [42, 97, 88];
scores.push(103); // valid
const first = scores[0]; // type: number | undefined

// Tuple: heterogeneous, fixed length
const user: [string, number] = ["Alice", 29];
user.push(true); // error: Argument of type 'boolean' is not assignable to parameter of type 'string | number'
const name = user[0]; // type: string (exact)

The array allows mutation and length changes. The tuple enforces structure. When an API returns a latitude/longitude pair, [number, number] guarantees two elements. number[] leaves the consumer guessing whether the array holds two values or twenty.

Tuples compose with union types. A function returning [data: User, error: null] | [data: null, error: Error] models a result type with discriminated positions. The caller destructures and checks the second element to know whether the first element is valid.

function fetchUser(id: string): [data: User, error: null] | [data: null, error: Error] {
  // implementation
}

const [data, error] = fetchUser("123");
if (error) {
  console.error(error.message);
} else {
  console.log(data.name); // TypeScript knows data is User here
}

Arrays do not support this pattern. The type system cannot track which index holds the discriminant and which holds the payload. Tuples give you that precision.

TypeScript tuple type checking in IDE

Labeled Tuple Elements: Self-Documenting Types That Show Up in Your IDE

Labeled elements annotate each position with a parameter name, surfacing that name in IDE tooltips and autocomplete without changing the runtime shape.

The syntax [x: number, y: number] looks like a function signature. That is deliberate. When you destructure const [x, y] = getCoordinates(), the IDE shows those labels in the autocomplete list. The compiler still enforces position, not property access.

// Without labels
type Unlabeled = [number, number];
const point: Unlabeled = [10, 20];
// IDE shows: const point: [number, number]

// With labels
type Labeled = [x: number, y: number];
const labeledPoint: Labeled = [10, 20];
// IDE shows: const labeledPoint: [x: number, y: number]
// Destructuring autocomplete suggests 'x' and 'y'

Labels do not change destructuring semantics. You can still write const [a, b] = labeledPoint and a will hold the first element. Labels serve documentation, not enforcement. The compiler does not reject const [latitude, longitude] = labeledPoint even though the labels say x and y.

The real payoff comes in function signatures. A handler accepting (event: [type: string, payload: unknown]) => void shows those labels when you hover over the parameter. Compare that to (event: [string, unknown]) => void, which forces the reader to guess what the second element represents.

Labeled tuples pair well with utility types. A tuple [id: string, count: number] passed to Readonly<[id: string, count: number]> preserves labels while preventing mutation. The labels survive through type transformations.

Per the TypeScript 4.0 handbook on labeled tuple elements, labels must appear on all elements or none. Mixing labeled and unlabeled positions within the same tuple triggers a compiler error. Consistency keeps the intent clear.

Variadic Tuple Types: Composing Function Signatures and Middleware Pipelines

Variadic tuples spread rest parameters into fixed positions, enabling type-safe function composition and middleware stacks without manual overload declarations.

Before variadic tuples, composing two functions meant writing overloads for every arity. A pipe utility accepting (a: A) => B and (b: B) => C could not infer types for a third function without another overload. Variadic tuples solve this with spreads.

// A compose function that preserves types
type Fn<T extends unknown[], R> = (...args: T) => R;

function compose<A extends unknown[], B, C>(
  f: Fn<A, B>,
  g: Fn<[B], C>
): Fn<A, C> {
  return (...args: A) => g(f(...args));
}

const addOne = (x: number) => x + 1;
const toString = (n: number) => n.toString();

const addThenStringify = compose(addOne, toString);
const result = addThenStringify(5); // type: string, value: "6"

The A extends unknown[] parameter captures the first function's argument tuple. The return type Fn<A, C> spreads that same tuple into the composed function's signature. TypeScript infers A as [number] when you pass addOne, then enforces that the composed function accepts number.

Middleware pipelines benefit more. An HTTP handler chain starts with [req: Request, res: Response] and each middleware adds context. Variadic tuples let you compose handlers that append parameters without losing type safety.

type Handler<T extends unknown[]> = (...args: T) => void | Promise<void>;

function withAuth<T extends [Request, Response, ...unknown[]]>(
  next: Handler<T>
): Handler<T> {
  return async (...args: T) => {
    const [req] = args;
    // auth logic
    return next(...args);
  };
}

function withLogging<T extends [Request, Response, ...unknown[]]>(
  next: Handler<T>
): Handler<T> {
  return async (...args: T) => {
    const [req] = args;
    console.log(req.url);
    return next(...args);
  };
}

const baseHandler: Handler<[Request, Response]> = (req, res) => {
  res.send("OK");
};

const protected = withAuth(withLogging(baseHandler));
// Type inferred: Handler<[Request, Response]>

The T extends [Request, Response, ...unknown[]] constraint preserves the leading two elements and allows trailing additions. Each middleware wraps the next without breaking the type chain. The final handler still accepts [Request, Response].

Variadic tuples also model Promise.all correctly. The built-in Promise.all<T extends readonly unknown[]>(values: T): Promise<{ [K in keyof T]: Awaited<T[K]> }> uses variadic spreads to map each promise to its resolved type. You get Promise<[string, number]> from Promise.all([Promise.resolve("a"), Promise.resolve(1)]) instead of Promise<(string | number)[]>.

When a Tuple Beats an Interface: Position, Destructuring, and Performance

Tuples win when position carries meaning, destructuring is idiomatic, or the structure is small and temporary.

An interface forces named property access. A tuple lets you destructure in the parameter list or assignment. When a hook returns [state, setState], destructuring is idiomatic. Forcing { state, setState } adds noise.

// Tuple: destructure at call site
function useCounter(): [count: number, increment: () => void] {
  // implementation
}
const [count, increment] = useCounter();

// Interface: named access
interface CounterResult {
  count: number;
  increment: () => void;
}
function useCounterObj(): CounterResult {
  // implementation
}
const { count, increment } = useCounterObj();

Both work. The tuple version mirrors React's useState convention. The interface version clarifies when return values exceed two or three fields. Pick based on idiom and size.

Criterion	Tuple	Interface
Element count	2-4 elements	4+ fields
Destructuring	`const [a, b] = fn()`	`const { a, b } = fn()`
Property renaming	Position-based, rename freely	Must match property names or use alias
Documentation	Labels in IDE, position implicit	Property names explicit
Type overhead	No keys, direct access	Property lookup, structural check
Extension	Cannot add optional trailing elements	Can extend with optional properties

Tuples avoid property name collisions. When merging two results, destructuring with different names is trivial: const [user, setUser] = useUser(); const [post, setPost] = usePost();. Interfaces require renaming: const { data: userData } = fetchUser(); const { data: postData } = fetchPost();.

Performance differences are negligible. Both compile to arrays or objects. Tuples carry less metadata at runtime (no property keys), but modern engines optimize both paths. Choose based on semantics, not speed.

Tuples also model discriminated unions compactly. A result type [ok: true, data: T] | [ok: false, error: Error] discriminates on the first element. Interfaces would need a separate status field and duplicate the discriminant check.

Readonly Tuples and as const: Preventing Mutations at Compile Time

Readonly tuples block push, pop, and index assignment; as const assertions lock down literal types and infer readonly tuples automatically.

A bare tuple [string, number] allows mutation. The compiler accepts tuple[0] = "new value" and tuple.push(42) (though push violates the fixed length, the runtime allows it). Wrapping in Readonly<...> or using readonly [string, number] prevents both.

// Mutable tuple
const mutable: [string, number] = ["Alice", 29];
mutable[0] = "Bob"; // allowed
mutable.push(100); // runtime error, but TypeScript allows it

// Readonly tuple
const immutable: readonly [string, number] = ["Alice", 29];
immutable[0] = "Bob"; // error: Index signature in type 'readonly [string, number]' only permits reading
immutable.push(100); // error: Property 'push' does not exist on type 'readonly [string, number]'

The readonly modifier removes push, pop, shift, unshift, splice, and index assignment. The tuple becomes a pure value. Functions accepting readonly [string, number] signal they will not mutate the input.

The as const assertion infers readonly tuples and narrows literals to their exact values. Without it, TypeScript widens ["Alice", 29] to (string | number)[]. With it, the type becomes readonly ["Alice", 29] with literal types.

// Without as const
const widened = ["Alice", 29]; // type: (string | number)[]

// With as const
const narrowed = ["Alice", 29] as const; // type: readonly ["Alice", 29]
const name = narrowed[0]; // type: "Alice" (literal)
const age = narrowed[1]; // type: 29 (literal)

This pairs well with exhaustive checks. A tuple ["success", "error", "pending"] as const gives you a union "success" | "error" | "pending" when spread. The compiler ensures switch statements cover all three cases.

const statuses = ["success", "error", "pending"] as const;
type Status = typeof statuses[number]; // "success" | "error" | "pending"

function handleStatus(status: Status) {
  switch (status) {
    case "success":
      return "OK";
    case "error":
      return "Failed";
    case "pending":
      return "Loading";
    default:
      const _exhaustive: never = status; // compiler error if a case is missing
      return _exhaustive;
  }
}

Readonly tuples prevent a class of bugs where shared state mutates unexpectedly. When a function returns readonly [User, Metadata], callers cannot accidentally modify the cached result. The type system enforces immutability without defensive copying.

Per the TypeScript handbook on const assertions, as const applies recursively. A nested tuple [["a", 1], ["b", 2]] as const becomes readonly [readonly ["a", 1], readonly ["b", 2]]. All layers lock down.

TypeScript readonly tuple preventing mutations

Real-World Patterns: API Returns, Event Handlers, and Multi-Value State

Tuples model API results with error/data pairs, event payloads with type and data, and stateful hooks returning value and setter.

A common pattern wraps API calls in a result tuple. The first element holds data on success, null on error. The second element holds the error or null. Destructuring gives immediate access to both.

async function fetchUserSafe(id: string): Promise<[data: User | null, error: Error | null]> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const user = await response.json();
    return [user, null];
  } catch (err) {
    return [null, err instanceof Error ? err : new Error(String(err))];
  }
}

const [user, error] = await fetchUserSafe("123");
if (error) {
  console.error("Failed to fetch user:", error.message);
} else {
  console.log("User:", user.name);
}

The caller checks the error element first. If null, the data element is safe to use. If present, the data element is null. The type system enforces this through union narrowing. No try/catch block needed at the call site.

Event handlers in frameworks like Svelte or custom event systems use tuples to pair event type with payload. A handler signature (event: [type: "click", target: HTMLElement]) => void documents both fields.

type ClickEvent = [type: "click", target: HTMLElement];
type KeyEvent = [type: "keydown", key: string];
type AppEvent = ClickEvent | KeyEvent;

function handleEvent(event: AppEvent) {
  const [type, payload] = event;
  if (type === "click") {
    console.log("Clicked:", payload.tagName);
  } else {
    console.log("Key pressed:", payload);
  }
}

The discriminant lives in the first position. TypeScript narrows payload based on type. A union of labeled tuples models tagged unions compactly.

Stateful hooks return tuples to mirror React conventions. A custom useToggle hook returns [value: boolean, toggle: () => void]. The caller destructures with meaningful names: const [isOpen, toggleOpen] = useToggle(false).

function useToggle(initial: boolean): [value: boolean, toggle: () => void] {
  const [value, setValue] = useState(initial);
  const toggle = () => setValue(v => !v);
  return [value, toggle];
}

Tuples keep the return compact. An interface would force { value, toggle }, which adds boilerplate. The tuple version reads cleaner when composing multiple hooks in a component.

For more on validating complex structures, see our guide on TypeScript form validators and custom validation logic, which covers zod and yup integration.

Common Pitfalls: Long Tuples, Type Inference Traps, and When to Use Objects Instead

Tuples lose clarity beyond four elements, inference fails when types are too similar, and objects win when order is arbitrary.

A tuple with six elements becomes unreadable. [string, number, boolean, string, Date, null] forces the reader to count positions. Named properties clarify intent faster than position.

// Bad: long tuple
type UserData = [id: string, name: string, age: number, email: string, createdAt: Date, deletedAt: Date | null];

// Better: interface
interface UserData {
  id: string;
  name: string;
  age: number;
  email: string;
  createdAt: Date;
  deletedAt: Date | null;
}

The interface version documents each field. The tuple version hides meaning behind indices. When you need more than four elements, switch to an object.

Type inference struggles when adjacent elements share types. A function returning [string, string] gives no hint which string holds the user ID and which holds the display name. Labels help, but the compiler cannot enforce destructuring order.

function getUser(): [id: string, name: string] {
  return ["u123", "Alice"];
}

const [name, id] = getUser(); // swapped, but compiler allows it

The destructured variables have the right types (both string), but the semantics are wrong. The compiler cannot catch this. When adjacent elements share types, consider an interface or an object with distinct keys.

Optional trailing elements create inference ambiguity. A tuple [string, number?] can hold one or two elements. Destructuring const [a, b] = tuple gives a: string and b: number | undefined, but you cannot tell from the type whether the tuple had one element or two.

type OptionalTuple = [name: string, age?: number];

const single: OptionalTuple = ["Alice"];
const double: OptionalTuple = ["Bob", 30];

const [name1, age1] = single; // age1: number | undefined
const [name2, age2] = double; // age2: number | undefined

The type system cannot distinguish at the call site. If the presence of the second element matters, model it as a discriminated union: [name: string] | [name: string, age: number].

Tuples also fail when order is arbitrary. A coordinate pair [x: number, y: number] has semantic order (horizontal, vertical). A user record with [email: string, phone: string] does not. Which comes first is a convention, not a constraint. Use an interface when order is arbitrary.

For a deeper dive into advanced type constraints, see our post on TypeScript generic constraints with extends and keyof.

Frequently Asked Questions

When should you use a labeled tuple instead of an interface?

Use a labeled tuple when the structure has 2-4 elements with semantic position order and the consumer will destructure it. Examples include coordinate pairs [x: number, y: number], React hook returns [state: T, setState: (val: T) => void], or result tuples [data: T | null, error: Error | null]. Use an interface when the structure exceeds four fields, when property names clarify intent better than position, or when order is arbitrary.

How do variadic tuple types improve function composition?

Variadic tuple types spread rest parameters into fixed positions, letting you compose functions without manual overloads. A compose utility can preserve the first function's argument tuple through type inference: compose<A extends unknown[], B, C>(f: (...args: A) => B, g: (b: B) => C): (...args: A) => C. The type system infers A from the first function and applies it to the composed result, maintaining type safety across the chain.

What happens when you use as const on a tuple literal?

The as const assertion infers a readonly tuple with literal types for each element. ["Alice", 29] as const becomes readonly ["Alice", 29] with types "Alice" and 29 instead of string and number. The readonly modifier prevents mutation, and the literal types enable exhaustive checking in discriminated unions. The assertion applies recursively to nested structures.

Can you extend a tuple type with additional elements?

TypeScript supports optional trailing elements with ? syntax: [required: string, optional?: number]. You cannot extend a named tuple type with inheritance the way you extend interfaces. Variadic tuple types allow composition: type Extended<T extends unknown[]> = [...T, extra: boolean] appends an element to the end. For dynamic extension, use rest elements: [first: string, ...rest: number[]].

When does a tuple perform better than an interface?

Tuples and interfaces both compile to runtime arrays or objects, and modern JavaScript engines optimize both paths aggressively. Tuples carry slightly less metadata (no property keys), but the performance difference is negligible in practice. Choose tuples for semantic reasons (position matters, destructuring is idiomatic) rather than performance. Microbenchmarks may show tiny differences, but they vanish under real workload variance.

Tuples in 2026: What You Should Reach For and When to Walk Away

Tuples deliver position-based type safety when destructuring is idiomatic and structure is small. Labeled elements clarify intent without runtime cost. Variadic spreads compose function signatures cleanly. Readonly tuples prevent mutation.

The pattern breaks at five elements. When property names clarify better than position, an interface wins. When adjacent elements share types, the compiler cannot catch swapped destructuring. When order is arbitrary, forcing a tuple sacrifices clarity for no gain.

Reach for tuples when returning small fixed-length collections from functions, modeling discriminated unions compactly, or composing middleware pipelines. Walk away when the structure grows past four fields, when naming beats numbering, or when the caller does not destructure. The type system gives you both tools. Use the one that documents intent.

For further refinement of type utilities, explore our coverage of Partial, Required, and DeepPartial patterns in TypeScript.

TypeScript `ReadonlyDeep` Without a Library: Writing the Recursive Utility Type Once and Never Again

jsmanifest — Tue, 27 Oct 2026 06:04:30 +0000

TypeScript `ReadonlyDeep<T>` Without a Library: Writing the Recursive Utility Type Once and Never Again

Why Built-In Readonly Isn't Enough

TypeScript's built-in Readonly<T> type applies immutability to top-level properties but stops there. Nested objects remain mutable. When a developer marks a configuration object as readonly and a teammate mutates a nested property three levels deep, the compiler stays silent. The bug appears in production.

Problem flow showing built-in Readonly allowing nested mutations

A recursive readonly type solves this. Every property at every depth becomes immutable. The compiler catches mutations before they ship.

Solution flow showing ReadonlyDeep preventing all mutations

Key Takeaways

TypeScript's Readonly<T> only protects top-level properties; nested objects remain mutable and cause silent bugs.
A recursive ReadonlyDeep<T> utility type applies immutability to all properties at every depth without runtime overhead.
The implementation requires handling primitives, functions, arrays, Maps, Sets, and circular references with conditional types.
Type-fest's version adds complexity for edge cases; a focused implementation works for most codebases in under 30 lines.
Compiler performance degrades past 10 nesting levels or 100+ properties; measure before applying to massive schemas.

Understanding the ReadonlyDeep Signature

The type signature needs to handle every TypeScript construct. Primitives like string, number, and boolean pass through unchanged. Functions preserve their signatures. Arrays become readonly arrays. Objects recurse into their properties.

Type hierarchy showing ReadonlyDeep branching by input type

The recursive case is where the type earns its place. For each property K in object T, the type constructs a new object with K mapped to ReadonlyDeep<T[K]>. The recursion stops when it hits a primitive or function.

TypeScript's conditional types make this possible. The pattern T extends Primitive ? T : ... lets the type branch based on structure. Each branch handles a different category.

The built-in Readonly<T> handles the shallow case. ReadonlyDeep<T> wraps it with recursion. The combination creates a type that descends through arbitrarily nested structures.

Building ReadonlyDeep: The Base Case and Recursive Logic

The implementation starts with a type alias for primitives. This includes string, number, boolean, symbol, bigint, undefined, and null. Functions count as primitives here because their internal structure does not require recursion.

type Primitive =
  | string
  | number
  | boolean
  | symbol
  | bigint
  | undefined
  | null;

type ReadonlyDeep<T> = T extends Primitive
  ? T
  : T extends Function
  ? T
  : T extends (infer U)[]
  ? ReadonlyArray<ReadonlyDeep<U>>
  : {
      readonly [K in keyof T]: ReadonlyDeep<T[K]>;
    };

The first condition checks if T is a primitive. If so, the type returns T unchanged. The second condition handles functions. The third condition matches arrays using the infer pattern and wraps them in ReadonlyArray.

The final case handles objects. The mapped type iterates over every key K in T. Each property becomes readonly, and the value type becomes ReadonlyDeep<T[K]>. The recursion happens here.

This version works for most cases. A configuration object with nested arrays and objects becomes fully immutable:

interface Config {
  database: {
    host: string;
    port: number;
    credentials: {
      username: string;
      password: string;
    };
  };
  features: string[];
}

type ImmutableConfig = ReadonlyDeep<Config>;

const config: ImmutableConfig = {
  database: {
    host: "localhost",
    port: 5432,
    credentials: {
      username: "admin",
      password: "secret",
    },
  },
  features: ["caching", "logging"],
};

// All of these produce compile-time errors:
config.database.port = 3306; // Error: Cannot assign to 'port'
config.database.credentials.password = "newpass"; // Error
config.features.push("metrics"); // Error: Property 'push' does not exist
config.features[0] = "telemetry"; // Error: Index signature is readonly

The compiler blocks every mutation attempt. No runtime checks. No library dependency.

TypeScript error panel showing blocked mutations on deeply nested readonly properties

Handling Edge Cases: Functions, Maps, Sets, and Arrays

The basic implementation breaks down with Map and Set. These types have methods like set and add that mutate internal state. TypeScript's ReadonlyMap and ReadonlySet types exist for this reason.

The extended version adds conditions for these collections:

type Primitive =
  | string
  | number
  | boolean
  | symbol
  | bigint
  | undefined
  | null;

type ReadonlyDeep<T> = T extends Primitive
  ? T
  : T extends Function
  ? T
  : T extends Map<infer K, infer V>
  ? ReadonlyMap<K, ReadonlyDeep<V>>
  : T extends Set<infer U>
  ? ReadonlySet<ReadonlyDeep<U>>
  : T extends (infer U)[]
  ? ReadonlyArray<ReadonlyDeep<U>>
  : {
      readonly [K in keyof T]: ReadonlyDeep<T[K]>;
    };

The Map branch infers key and value types, wraps the value in ReadonlyDeep, and returns ReadonlyMap. The Set branch does the same with ReadonlySet. Both prevent mutations while preserving read operations.

Functions with properties require careful handling. A function can have properties attached to it, and those properties should become readonly:

interface Logger {
  (message: string): void;
  level: string;
}

type ReadonlyLogger = ReadonlyDeep<Logger>;

const logger: ReadonlyLogger = Object.assign(
  (message: string) => console.log(message),
  { level: "info" }
);

logger("test"); // Works
logger.level = "debug"; // Error: Cannot assign to 'level'

The function condition in the type needs to come after the primitive check but before the object recursion. This preserves the function signature while applying readonly to any attached properties.

Arrays of arrays require the recursion to work properly. The type string[][] becomes ReadonlyArray<ReadonlyArray<string>>. Each level of nesting applies both ReadonlyArray and ReadonlyDeep to the inner type.

For more on working with readonly collections, see ReadonlyMap and ReadonlySet in TypeScript.

ReadonlyDeep vs type-fest vs Manual Implementation

The type-fest library provides a ReadonlyDeep implementation with additional features. It handles classes, preserves function properties, and includes special cases for built-in types. The tradeoff is complexity.

Comparison of three ReadonlyDeep approaches

The custom implementation covers objects, arrays, functions, Maps, and Sets. This handles 95% of use cases in application code. Type-fest adds support for classes with private fields, WeakMaps, Promises, and other specialized types.

Here's the comparison on a complex type:

interface APISchema {
  users: Map<
    string,
    {
      profile: {
        name: string;
        tags: string[];
      };
      settings: Set<string>;
    }
  >;
  metadata: {
    version: number;
    handlers: Array<(data: unknown) => void>;
  };
}

// Custom implementation handles this correctly:
type ImmutableSchema = ReadonlyDeep<APISchema>;

// type-fest adds these guarantees:
// - Class instances preserve private field types
// - WeakMap and WeakSet get readonly versions
// - Promise values become readonly
// - Tuple types preserve length and ordering

For most codebases, the custom version works. The compiler errors guide you when edge cases appear. Adding type-fest as a dependency makes sense when you hit repeated gaps in coverage.

The maintenance burden differs. A custom utility type lives in the codebase and requires updates when TypeScript adds new built-in types. Type-fest tracks these changes and ships updates.

Teams building component libraries or TypeScript tooling benefit from type-fest's thoroughness. Application developers building features on a known stack rarely need that level of coverage.

For related patterns on partial immutability, see Partial, Required, and DeepPartial in TypeScript.

Real-World Use Cases: API Responses and Configuration Objects

API response types become safer with ReadonlyDeep. A response handler receives data from the network and should not modify it. The readonly constraint prevents accidental mutations that break caching or introduce race conditions.

interface UserResponse {
  user: {
    id: string;
    profile: {
      name: string;
      email: string;
      preferences: {
        theme: string;
        notifications: string[];
      };
    };
  };
  metadata: {
    timestamp: number;
    version: string;
  };
}

async function fetchUser(
  id: string
): Promise<ReadonlyDeep<UserResponse>> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

async function displayUser(id: string) {
  const data = await fetchUser(id);

  // All mutation attempts blocked:
  data.user.profile.name = "Modified"; // Error
  data.user.profile.preferences.notifications.push("email"); // Error
  data.metadata.timestamp = Date.now(); // Error

  // Reading works normally:
  console.log(data.user.profile.name);
  console.log(data.user.profile.preferences.theme);
}

Data flow showing readonly API response preventing mutations

Configuration objects gain the same protection. Application config loads once at startup and should never change. Making it readonly catches bugs where code tries to modify settings based on runtime conditions.

interface AppConfig {
  server: {
    port: number;
    host: string;
    ssl: {
      enabled: boolean;
      certPath: string;
    };
  };
  database: {
    connections: Array<{
      name: string;
      url: string;
      poolSize: number;
    }>;
  };
  features: Map<string, boolean>;
}

let config: ReadonlyDeep<AppConfig>;

function loadConfig(): ReadonlyDeep<AppConfig> {
  // Load from environment or config file
  return {
    server: {
      port: 3000,
      host: "0.0.0.0",
      ssl: {
        enabled: true,
        certPath: "/etc/ssl/cert.pem",
      },
    },
    database: {
      connections: [
        {
          name: "primary",
          url: "postgresql://localhost/db",
          poolSize: 10,
        },
      ],
    },
    features: new Map([
      ["caching", true],
      ["telemetry", false],
    ]),
  };
}

function initializeApp() {
  config = loadConfig();

  // Runtime modifications blocked:
  config.server.port = 4000; // Error
  config.database.connections[0].poolSize = 20; // Error
  config.features.set("logging", true); // Error
}

IDE tooltip showing readonly error when attempting to modify nested config property

Form validation schemas work well with readonly types. The schema defines structure and constraints. Validators read from it but should not modify it. See Custom Form Validators in TypeScript for validator patterns.

State management libraries benefit from readonly types. Redux state, Zustand stores, and React context values all gain safety when typed as ReadonlyDeep. The compiler prevents direct mutations and forces proper update patterns.

Performance Considerations and Compiler Limits

TypeScript's type checker has recursion limits. Deep nesting or large object types can hit these limits and cause compilation errors. The practical limit sits around 10 levels of nesting for complex types.

Type checking performance showing degradation with nesting depth

A type with 100 properties at 3 levels deep creates 100^3 = 1,000,000 type instantiations. The compiler caches these, but initial compilation takes time. Watch for slow type checking during development.

The workaround is to limit recursion depth. Add a depth parameter that decrements with each recursion:

type Primitive =
  | string
  | number
  | boolean
  | symbol
  | bigint
  | undefined
  | null;

type ReadonlyDeep<T, Depth extends number = 10> = Depth extends 0
  ? Readonly<T>
  : T extends Primitive
  ? T
  : T extends Function
  ? T
  : T extends Map<infer K, infer V>
  ? ReadonlyMap<K, ReadonlyDeep<V, Prev<Depth>>>
  : T extends Set<infer U>
  ? ReadonlySet<ReadonlyDeep<U, Prev<Depth>>>
  : T extends (infer U)[]
  ? ReadonlyArray<ReadonlyDeep<U, Prev<Depth>>>
  : {
      readonly [K in keyof T]: ReadonlyDeep<T[K], Prev<Depth>>;
    };

type Prev<N extends number> = N extends 0
  ? 0
  : N extends 1
  ? 0
  : N extends 2
  ? 1
  : N extends 3
  ? 2
  : N extends 4
  ? 3
  : N extends 5
  ? 4
  : N extends 6
  ? 5
  : N extends 7
  ? 6
  : N extends 8
  ? 7
  : N extends 9
  ? 8
  : N extends 10
  ? 9
  : never;

This version stops recursing after 10 levels and falls back to shallow Readonly. The Prev helper decrements the depth counter. When depth reaches zero, recursion stops.

Measure compilation time with tsc --diagnostics. Look for the "Type checking time" metric. If it exceeds one second, investigate which types cause the slowness.

Large codebases should apply ReadonlyDeep selectively. Configuration objects, API responses, and constants benefit from it. Internal implementation types that change frequently create unnecessary compilation overhead.

The type system overhead is zero at runtime. ReadonlyDeep is purely a compile-time construct. The JavaScript output contains no traces of it.

Frequently Asked Questions

How does ReadonlyDeep differ from const assertions?

Const assertions make literal types as narrow as possible and add shallow readonly to objects. ReadonlyDeep applies deep immutability to existing type definitions. Use const assertions for inline objects and ReadonlyDeep for reusable types.

Can ReadonlyDeep handle circular references?

No. Circular type references cause infinite recursion in TypeScript's type checker. The depth-limited version prevents compiler hangs but does not make circular structures readonly. Avoid circular references or use shallow Readonly for those cases.

Does ReadonlyDeep work with generics?

Yes. Pass generic types to ReadonlyDeep like any other type. The recursion applies to whatever type the generic resolves to at usage time.

Will ReadonlyDeep prevent all runtime mutations?

No. TypeScript types disappear at runtime. ReadonlyDeep provides compile-time safety only. Use Object.freeze() for runtime immutability or combine both approaches for defense in depth.

Should every type use ReadonlyDeep by default?

No. Apply it to data that should not change: configuration, API responses, constants. Internal implementation types that undergo frequent mutations benefit from normal mutability. Overuse creates friction without safety gains.

Write It Once, Use It Forever

The ReadonlyDeep<T> utility type solves the nested mutability problem that built-in Readonly<T> leaves open. Thirty lines of code eliminate an entire class of bugs. The compiler catches mutations at every depth before they reach production.

The implementation handles objects, arrays, functions, Maps, and Sets. Edge cases exist but rarely matter in application code. Teams that need comprehensive coverage can reach for type-fest. Teams building features on standard types can write this once and never think about it again.

Configuration objects and API responses gain immediate safety benefits. State management becomes more predictable. The type system enforces immutability contracts that previously existed only in documentation.

Compilation time matters for large schemas. Measure performance and limit recursion depth when needed. The tradeoff between safety and build speed is concrete and measurable.

Adding this utility type to a codebase takes five minutes and prevents mutations that take hours to debug.

DEV Community: jsmanifest

Claude Code Diff Verification in 2026: How to Make Your Agent Assert Its Own Edits Did Not Break the Build

Claude Code Diff Verification in 2026: How to Make Your Agent Assert Its Own Edits Did Not Break the Build

Key Takeaways

Understanding What Claude Code Can and Cannot Verify on Its Own

Building a Post-Edit Verification Hook That Runs git diff, Tests, and Type Checks

Assertion Patterns: Making the Agent Verify Its Own Changes Before You Approve

Comparison: Manual Review vs Hook-Based Verification vs Full CI Integration

Production Patterns: Pre-Commit Checks, Test Suites, and What to Auto-Accept

Frequently Asked Questions

What happens if the Stop hook blocks eight times in a row?

Can I disable the Stop hook for one session without editing settings.json?

Should the Stop hook run the full test suite or only unit tests?

Does the Stop hook work with subagents and background sessions?

What if the Stop hook itself has a bug?

Conclusion: Trust but Verify

Sources

TypeScript `const` Enums Are Deprecated: What to Migrate to and Why the Compiler Team Made the Call

TypeScript const Enums Are Deprecated: What to Migrate to and Why the Compiler Team Made the Call

Key Takeaways

The Technical Problems With Const Enums

How Const Enums Break in Isolated Module Compilation

Migration Path 1: Union Types With as const

Migration Path 2: Plain const Objects

Const Enums vs Regular Enums vs Modern Alternatives

What to Do With Existing Const Enum Code

Frequently Asked Questions

Can I still use regular enums without the const modifier?

Does preserveConstEnums make const enums safe to use?

Why not just ban const enums with a linter rule?

Will regular enums eventually be deprecated too?

How do union types handle bitwise operations like flags?

The Future of Enums in TypeScript

TypeScript Function Overloads in 2026: When They Clarify and When They Mislead the Caller

TypeScript Function Overloads in 2026: When They Clarify and When They Mislead the Caller

Key Takeaways

How TypeScript Resolves Overload Signatures: First Match Wins

When Overloads Clarify Intent: DOM APIs and Multiple Signatures

When Overloads Mislead: Order Matters and Hidden Complexity

Overloads vs Union Types: Choosing the Right Tool in 2026

Production Patterns: Writing Maintainable Overload Sets

Common Mistakes: Inconsistent Return Types and Unreachable Signatures

Frequently Asked Questions

When should a function use overloads instead of union types?

Does TypeScript choose the most specific overload signature or the first match?

Why does the implementation signature stay invisible to callers?

Can overload signatures have different parameter counts?

What compiler options affect overload behavior?

Conclusion

TypeScript `globalThis` Typing in 2026: Safely Adding Properties to the Global Scope Without `any`

TypeScript globalThis Typing in 2026: Safely Adding Properties to the Global Scope Without any

Why globalThis Typing Still Matters in 2026

Key Takeaways

The Problem: Adding Properties to globalThis Without any

Declaration Merging: The Official TypeScript Pattern

globalThis vs window vs global: When Each Pattern Breaks

Module vs Script Context: Why declare global Sometimes Fails

Real-World Patterns: Environment Variables, Feature Flags, and Runtime Config

Environment Variables

Feature Flags

Server-Side Rendering Config

Testing and Cleanup: Avoiding Pollution Between Test Suites

When NOT to Use globalThis: Better Alternatives for Most Use Cases

Module-Scoped Constants

Dependency Injection

Context Objects

When globalThis Is Actually Correct

Frequently Asked Questions

Can I declare multiple properties on globalThis in separate files?

Why does my globalThis declaration not work in a .ts file?

How do I prevent accidental writes to typed global properties?

Does globalThis typing work with strictNullChecks enabled?

What happens if two libraries declare the same global property with different types?

Conclusion

TypeScript `@throws` JSDoc and Error Typing in 2026: Why Exceptions Are Still Untyped and What to Do About It

TypeScript @throws JSDoc and Error Typing in 2026: Why Exceptions Are Still Untyped and What to Do About It

Key Takeaways

Why TypeScript Still Doesn't Type Exceptions in 2026

The @throws JSDoc Tag: What It Provides and What It Doesn't

Building Type-Safe Error Handling Without Language Support

TypeScript `const` Enums Are Deprecated: What to Migrate to and Why the Compiler Team Made the Call

TypeScript `globalThis` Typing in 2026: Safely Adding Properties to the Global Scope Without `any`

TypeScript `@throws` JSDoc and Error Typing in 2026: Why Exceptions Are Still Untyped and What to Do About It

Next.js Prefetching in App Router: How `<Link>` Partial Prefetch Works and Why Your Pages Still Feel Slow

Next.js 16 `use cache` Directive: Granular Caching at the Function Level and What It Replaces

What `use cache` Replaces: unstable_cache, fetch Options, and Implicit Caching

How `use cache` Works: Function-Level and Component-Level Caching

Using `cacheLife()` for Granular Cache Control

Migration Patterns: Converting Legacy Caching to `use cache`

`use cache` vs Data Cache vs Full Route Cache: Understanding the Cache Hierarchy

When should you use `use cache: remote` instead of the default in-memory cache?

Can you cache Server Actions with `use cache`?

What happens when you call `revalidateTag()` with a tag that does not exist?

Can you use `use cache` in Client Components?