Skip to content

Add unstable_io shim for next/cache export #805

@github-actions

Description

@github-actions

Summary

Next.js added a new unstable_io() export from next/cache behind the experimental.unstableIO config flag. This is a metasyntactic IO boundary that, during prerendering with cache components, returns a hanging promise to prevent execution of code that follows it. In all other contexts it resolves as a fulfilled thenable that React can unwrap synchronously.

Upstream

What changed

  • New export unstable_io from next/cache (both server and client/browser paths)
  • New config option experimental.unstableIO (boolean, default false)
  • New env variable process.env.__NEXT_UNSTABLE_IO
  • Server implementation in packages/next/src/server/request/io.ts with behavior varying by work unit type:
    • request: resolves immediately (production) or uses staged rendering (dev)
    • prerender / prerender-client / prerender-runtime: returns a hanging promise to prevent prerendering past the IO boundary
    • cache / unstable-cache / generate-static-params / prerender-legacy: resolves immediately
  • Client/browser implementation always resolves immediately (returns a pre-resolved thenable)
  • Throws if called without experimental.unstableIO enabled

Impact on vinext

vinext shims next/cache and needs to add unstable_io to the shim. Since vinext primarily targets Cloudflare Workers (no prerendering context), the simplest correct implementation is:

  1. Add unstable_io to the next/cache shim exports
  2. Have it return a pre-resolved thenable (same as the browser implementation)
  3. Optionally: gate behind experimental.unstableIO config check and throw if not enabled (matching Next.js behavior)

This is gated behind an experimental flag and not ready for general use, so this is low priority.

Metadata

Metadata

Assignees

No one assigned

    Labels

    nextjs-trackingTracking issue for a Next.js canary change relevant to vinext

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions