Stabilize unstable_instant

This API has experimental modes for build validation but the dev validation is going to be stable in the next release.

Author: gnoff

.agents/skills/insight-error-page/SKILL.md

@@ -132,17 +132,17 @@ kind: insight
 - `use cache` directive (not `"use cache"` in prose)
 - Cache Components (capitalized)
 - static shell (link to `/docs/app/glossary#static-shell`)
-- `unstable_instant` (not `instant`)
+- `instant` (not `instant`)
 - `cacheLife` / `cacheTag` / `revalidateTag` / `updateTag` — use published names exactly
 - `connection()` from `next/server`
 - Client Component / Server Component (capitalized)
 - [prerendering](/docs/app/glossary#prerendering) — always linked on first use
 
 ### Allow blocking route section (canonical pattern)
 
-When the framework card set includes `unstable_instant = false` (group `block`), use the canonical `## Allow blocking route` section shape. All pages with this fix must match. Cross-page consistency matters — diverging from this shape produces a page that reads like an outlier.
+When the framework card set includes `instant = false` (group `block`), use the canonical `## Allow blocking route` section shape. All pages with this fix must match. Cross-page consistency matters — diverging from this shape produces a page that reads like an outlier.
 
-**Intro**: One paragraph explaining what setting `unstable_instant` to `false` does and what the trade-off is. Optional second paragraph noting when this is _rarely_ the right answer (for example, on client-hook or cache fixes where a Suspense boundary is almost always feasible). Phrase the rarity directly. Do not write `Confirm with the user` in body prose — that phrasing belongs in `prompt={...}` agent strings, not in the page the user reads.
+**Intro**: One paragraph explaining what setting `instant` to `false` does and what the trade-off is. Optional second paragraph noting when this is _rarely_ the right answer (for example, on client-hook or cache fixes where a Suspense boundary is almost always feasible). Phrase the rarity directly. Do not write `Confirm with the user` in body prose — that phrasing belongs in `prompt={...}` agent strings, not in the page the user reads.
 
 **Patterns**: For page-body errors (runtime data, uncached data, client hooks), use both `#### Opt the page out` and `#### Opt the layout out`. For viewport errors, use only `#### Opt the layout out` (viewport always lives on a layout). Each pattern has:
 
@@ -171,8 +171,8 @@ Every insight page ends (just before `## Useful links`) with the canonical opt-o
 
 Instant-navigation validation runs by default in [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) apps and is what surfaces this error.
 
-- **One segment**: add [`export const unstable_instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. The segment is exempted from validation.
-- **Entire app**: set [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults) to `'manual-warning'` in `next.config`. Validation runs only on segments that explicitly export `unstable_instant`.
+- **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. The segment is exempted from validation.
+- **Entire app**: set [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults) to `'manual-warning'` in `next.config`. Validation runs only on segments that explicitly export `instant`.
 
 See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
 ```

crates/next-core/src/segment_config.rs

@@ -119,7 +119,7 @@ pub struct NextSegmentConfig {
     pub generate_static_params: Option<Span>,
     #[turbo_tasks(trace_ignore)]
     #[bincode(with_serde)]
-    pub unstable_instant: Option<Span>,
+    pub instant: Option<Span>,
     #[turbo_tasks(trace_ignore)]
     #[bincode(with_serde)]
     pub prefetch: Option<Span>,
@@ -534,15 +534,15 @@ pub async fn parse_segment_config_from_source(
             .await?;
         }
 
-        if let Some(span) = config.unstable_instant {
+        if let Some(span) = config.instant {
             invalid_config(
                 source,
-                "unstable_instant",
+                "instant",
                 span,
                 rcstr!(
-                    "\"unstable_instant\" is a route segment config and can only be used when the \
-                     segment is a Server Component module. Remove the \"use client\" directive to \
-                     use this API."
+                    "\"instant\" is a route segment config and can only be used when the segment \
+                     is a Server Component module. Remove the \"use client\" directive to use \
+                     this API."
                 ),
                 None,
                 IssueSeverity::Error,
@@ -984,8 +984,8 @@ async fn parse_config_value(
         "generateStaticParams" => {
             config.generate_static_params = Some(span);
         }
-        "unstable_instant" => {
-            config.unstable_instant = Some(span);
+        "instant" => {
+            config.instant = Some(span);
         }
         "prefetch" => {
             config.prefetch = Some(span);

crates/next-custom-transforms/src/transforms/debug_instant_stack.rs

@@ -53,21 +53,21 @@ struct DebugInstantStackPass {
 }
 
 /// Given an export specifier, returns `Some((exported_name, local_name))` if
-/// the exported name is `unstable_instant`.
+/// the exported name is `instant`.
 fn get_instant_specifier_names(specifier: &ExportSpecifier) -> Option<(&Ident, &Ident)> {
     match specifier {
-        // `export { orig as unstable_instant }`
+        // `export { orig as instant }`
         ExportSpecifier::Named(ExportNamedSpecifier {
             exported: Some(ModuleExportName::Ident(exported)),
             orig: ModuleExportName::Ident(orig),
             ..
-        }) if exported.sym == "unstable_instant" => Some((exported, orig)),
-        // `export { unstable_instant }`
+        }) if exported.sym == "instant" => Some((exported, orig)),
+        // `export { instant }`
         ExportSpecifier::Named(ExportNamedSpecifier {
             exported: None,
             orig: ModuleExportName::Ident(orig),
             ..
-        }) if orig.sym == "unstable_instant" => Some((orig, orig)),
+        }) if orig.sym == "instant" => Some((orig, orig)),
         _ => None,
     }
 }
@@ -106,26 +106,26 @@ impl VisitMut for DebugInstantStackPass {
 
         for item in items.iter() {
             match item {
-                // `export const unstable_instant = ...`
+                // `export const instant = ...`
                 ModuleItem::ModuleDecl(ModuleDecl::ExportDecl(export_decl)) => {
                     if let Decl::Var(var_decl) = &export_decl.decl {
                         for decl in &var_decl.decls {
                             if let Pat::Ident(ident) = &decl.name
-                                && ident.id.sym == "unstable_instant"
+                                && ident.id.sym == "instant"
                                 && let Some(init) = &decl.init
                             {
                                 self.instant_export_span = Some(init.span());
                             }
                         }
                     }
                 }
-                // `export { unstable_instant }` or `export { x as unstable_instant }`
+                // `export { instant }` or `export { x as instant }`
                 // with or without `from '...'`
                 ModuleItem::ModuleDecl(ModuleDecl::ExportNamed(named)) => {
                     for specifier in &named.specifiers {
                         if let Some((_exported, orig)) = get_instant_specifier_names(specifier) {
                             if named.src.is_some() {
-                                // Re-export: `export { unstable_instant } from './config'`
+                                // Re-export: `export { instant } from './config'`
                                 // Point at the export specifier itself
                                 self.instant_export_span = Some(specifier.span());
                             } else {
@@ -156,7 +156,7 @@ impl VisitMut for DebugInstantStackPass {
             }
 
             let mut cons = quote!(
-                "function unstable_instant() {
+                "function instant() {
                     const error = $new_error
                     error.name = 'Instant Validation'
                     return error
@@ -165,7 +165,7 @@ impl VisitMut for DebugInstantStackPass {
             );
 
             // Patch source_span onto the Function
-            // for sourcemap mapping back to the unstable_instant config value
+            // for sourcemap mapping back to the instant config value
             if let Expr::Fn(f) = &mut cons {
                 f.function.span = source_span;
             }

crates/next-custom-transforms/src/transforms/react_server_components.rs

@@ -956,7 +956,7 @@ impl ReactServerComponentValidator {
                             ),
                         );
                     }
-                    "unstable_instant" if !self.cache_components_enabled => {
+                    "instant" if !self.cache_components_enabled => {
                         possibly_invalid_exports.insert(
                             export_name.clone(),
                             (

crates/next-custom-transforms/tests/errors/react-server-components/server-graph/cache-components/instant-with-cache-components/output.js

@@ -1,4 +1,4 @@
-export const unstable_instant = {
+export const instant = {
     prefetch: 'static'
 };
 export default function Page() {

crates/next-custom-transforms/tests/errors/react-server-components/server-graph/cache-components/instant-with-cache-components/page.js

@@ -1,4 +1,4 @@
-export const unstable_instant = { prefetch: 'static' }
+export const instant = { prefetch: 'static' }
 
 export default function Page() {
   return <div>Hello</div>

crates/next-custom-transforms/tests/errors/react-server-components/server-graph/instant-requires-cache-components/output.js

@@ -1,4 +1,4 @@
-export const unstable_instant = {
+export const instant = {
     prefetch: 'static'
 };
 export default function Page() {

crates/next-custom-transforms/tests/errors/react-server-components/server-graph/instant-requires-cache-components/output.stderr

@@ -1,5 +1,5 @@
-  x Route segment config "unstable_instant" requires `nextConfig.cacheComponents` to be enabled.
+  x Route segment config "instant" requires `nextConfig.cacheComponents` to be enabled.
    ,-[input.js:1:1]
- 1 | export const unstable_instant = { prefetch: 'static' }
-   :              ^^^^^^^^^^^^^^^^
+ 1 | export const instant = { prefetch: 'static' }
+   :              ^^^^^^^
    `----

crates/next-custom-transforms/tests/errors/react-server-components/server-graph/instant-requires-cache-components/page.js

@@ -1,4 +1,4 @@
-export const unstable_instant = { prefetch: 'static' }
+export const instant = { prefetch: 'static' }
 
 export default function Page() {
   return <div>Hello</div>

crates/next-custom-transforms/tests/fixture/debug-instant-stack/with-aliased-export/input.js

@@ -1,5 +1,5 @@
-const instant = { prefetch: 'static' }
-export { instant as unstable_instant }
+const instantConfig = { prefetch: 'static' }
+export { instantConfig as instant }
 
 export default function Page() {
   return <div>Hello</div>