cloudflare / cloudflare/vinext

Support `unstable_prefetch` route segment config

Open
#849 2 comments 0 reactions 0 assignees View on GitHub
nextjs-tracking
Dominant language
TypeScript
Stars
8.8k
Forks
406
Avg merge
2d 6h
Merged PRs (30d)
120

Description

## Next.js Change

Next.js added a new `unstable_prefetch` route segment config option, decoupled from `unstable_instant`.

**Commit:** https://github.com/vercel/next.js/commit/ac6d9932a64aa1f927c5dda2f70a39da4dc777fd
**PR:** [#92754](https://github.com/vercel/next.js/pull/92754)

## What Changed

A new route segment config export `unstable_prefetch` was added to App Router pages/layouts:

```ts
export const unstable_prefetch = 'runtime' // or 'static'
```

Key details:
- **Type:** `'static' | 'runtime'` — `'static'` is a no-op (default), `'runtime'` enables runtime prefetching
- **Requires `cacheComponents: true`** in `next.config.js` — throws a build error otherwise
- **Server Components only** — throws a build error if used in a `"use client"` module
- **Decoupled from `unstable_instant`** — previously, runtime prefetching was configured via `unstable_instant: { prefetch: 'runtime' }`. Now `unstable_prefetch` controls prefetching independently, and `unstable_instant` is purely for instant validation
- The `create-component-tree.tsx` now reads `unstable_prefetch` instead of `unstable_instant.prefetch` to determine `hasRuntimePrefetch`

## Impact on vinext

vinext's route segment config parsing (`routing/app-router.ts`, `get-page-static-info` equivalent) should recognize `unstable_prefetch` as a valid export to avoid spurious warnings. The actual runtime prefetching behavior is not something vinext needs to implement immediately (it's experimental and tied to `cacheComponents`), but the config should be parsed and acknowledged.

## Files Changed (non-test)

- `packages/next/src/build/segment-config/app/app-segment-config.ts` — added `PrefetchSchema`, `Prefetch` type, and `unstable_prefetch` to the schema
- `packages/next/src/build/analysis/get-page-static-info.ts` — added validation (requires `cacheComponents`, disallows `"use client"`)
- `packages/next/src/server/app-render/create-component-tree.tsx` — reads `unstable_prefetch` instead of `unstable_instant.prefetch`
- `crates/next-core/src/segment_config.rs` — Turbopack-side parsing of the new config

Contributor guide

Open the contributing guide

Research direction

Start in vinext's routing/app-router.ts and the get-page-static-info equivalent to trace how route segment config exports are parsed and warned about. Add recognition for unstable_prefetch without implementing runtime prefetching, then verify that valid values are acknowledged without spurious warnings.

Written by the indexing model from the issue text.

Assessment

Tech stack
next.js, typescript
Domain
web-dev
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.