Unverified Commit d424aa8e authored by Josh Story's avatar Josh Story Committed by GitHub

Stabilize `unstable_instant` (#94578)

This API has experimental modes for build validation but the dev
validation is going to be stable in the next release.
parent 9e4d718d
...@@ -132,7 +132,7 @@ kind: insight ...@@ -132,7 +132,7 @@ kind: insight
- `use cache` directive (not `"use cache"` in prose) - `use cache` directive (not `"use cache"` in prose)
- Cache Components (capitalized) - Cache Components (capitalized)
- static shell (link to `/docs/app/glossary#static-shell`) - static shell (link to `/docs/app/glossary#static-shell`)
- `unstable_instant` (not `instant`) - `instant` (not `instant`)
- `cacheLife` / `cacheTag` / `revalidateTag` / `updateTag` — use published names exactly - `cacheLife` / `cacheTag` / `revalidateTag` / `updateTag` — use published names exactly
- `connection()` from `next/server` - `connection()` from `next/server`
- Client Component / Server Component (capitalized) - Client Component / Server Component (capitalized)
...@@ -140,9 +140,9 @@ kind: insight ...@@ -140,9 +140,9 @@ kind: insight
### Allow blocking route section (canonical pattern) ### 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: **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:
...@@ -156,7 +156,7 @@ After the pattern snippets, include a "Use either pattern when:" bulleted list ( ...@@ -156,7 +156,7 @@ After the pattern snippets, include a "Use either pattern when:" bulleted list (
**Gotchas** (mandatory bullets, in this order): **Gotchas** (mandatory bullets, in this order):
- Layout opt-out exempts every route in the subtree, not only the layout itself. Audit child routes before opting a shared layout out. - Setting `instant` to `false` opts out only the segment that exports it. Descendant segments remain validated by their own config or the global default.
- This export does not disable prerendering. The route still prerenders if it can. It only silences the instant-navigation validation error. - This export does not disable prerendering. The route still prerenders if it can. It only silences the instant-navigation validation error.
- Page-specific gotchas (for example, viewport pages add framework-synthesized routes gotcha) come after the two canonical bullets. - Page-specific gotchas (for example, viewport pages add framework-synthesized routes gotcha) come after the two canonical bullets.
...@@ -164,15 +164,16 @@ After the pattern snippets, include a "Use either pattern when:" bulleted list ( ...@@ -164,15 +164,16 @@ After the pattern snippets, include a "Use either pattern when:" bulleted list (
### Don't want this validation? ### Don't want this validation?
Every insight page ends (just before `## Useful links`) with the canonical opt-out block. It teaches the reader how to silence validation per-segment and app-wide, since instant-navigation validation runs by default in Cache Components apps. Copy verbatim: Every insight page ends (just before `## Useful links`) with the canonical opt-out block. It teaches the reader how to silence validation per-segment, subtree-wide, and app-wide, since instant-navigation validation runs by default in Cache Components apps. Copy verbatim:
```mdx ```mdx
## Don't want this validation? ## Don't want this validation?
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. 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. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **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`. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
``` ```
......
...@@ -121,7 +121,7 @@ pub struct NextSegmentConfig { ...@@ -121,7 +121,7 @@ pub struct NextSegmentConfig {
pub generate_static_params: Option<Span>, pub generate_static_params: Option<Span>,
#[turbo_tasks(trace_ignore)] #[turbo_tasks(trace_ignore)]
#[bincode(with_serde)] #[bincode(with_serde)]
pub unstable_instant: Option<Span>, pub instant: Option<Span>,
#[turbo_tasks(trace_ignore)] #[turbo_tasks(trace_ignore)]
#[bincode(with_serde)] #[bincode(with_serde)]
pub prefetch: Option<Span>, pub prefetch: Option<Span>,
...@@ -549,15 +549,15 @@ pub async fn parse_segment_config_from_source( ...@@ -549,15 +549,15 @@ pub async fn parse_segment_config_from_source(
.await?; .await?;
} }
if let Some(span) = config.unstable_instant { if let Some(span) = config.instant {
invalid_config( invalid_config(
source, source,
"unstable_instant", "instant",
span, span,
rcstr!( rcstr!(
"\"unstable_instant\" is a route segment config and can only be used when the \ "\"instant\" is a route segment config and can only be used when the segment \
segment is a Server Component module. Remove the \"use client\" directive to \ is a Server Component module. Remove the \"use client\" directive to use \
use this API." this API."
), ),
None, None,
IssueSeverity::Error, IssueSeverity::Error,
...@@ -1001,8 +1001,8 @@ async fn parse_config_value( ...@@ -1001,8 +1001,8 @@ async fn parse_config_value(
"generateStaticParams" => { "generateStaticParams" => {
config.generate_static_params = Some(span); config.generate_static_params = Some(span);
} }
"unstable_instant" => { "instant" => {
config.unstable_instant = Some(span); config.instant = Some(span);
} }
"prefetch" => { "prefetch" => {
config.prefetch = Some(span); config.prefetch = Some(span);
......
...@@ -53,21 +53,21 @@ struct DebugInstantStackPass { ...@@ -53,21 +53,21 @@ struct DebugInstantStackPass {
} }
/// Given an export specifier, returns `Some((exported_name, local_name))` if /// 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)> { fn get_instant_specifier_names(specifier: &ExportSpecifier) -> Option<(&Ident, &Ident)> {
match specifier { match specifier {
// `export { orig as unstable_instant }` // `export { orig as instant }`
ExportSpecifier::Named(ExportNamedSpecifier { ExportSpecifier::Named(ExportNamedSpecifier {
exported: Some(ModuleExportName::Ident(exported)), exported: Some(ModuleExportName::Ident(exported)),
orig: ModuleExportName::Ident(orig), orig: ModuleExportName::Ident(orig),
.. ..
}) if exported.sym == "unstable_instant" => Some((exported, orig)), }) if exported.sym == "instant" => Some((exported, orig)),
// `export { unstable_instant }` // `export { instant }`
ExportSpecifier::Named(ExportNamedSpecifier { ExportSpecifier::Named(ExportNamedSpecifier {
exported: None, exported: None,
orig: ModuleExportName::Ident(orig), orig: ModuleExportName::Ident(orig),
.. ..
}) if orig.sym == "unstable_instant" => Some((orig, orig)), }) if orig.sym == "instant" => Some((orig, orig)),
_ => None, _ => None,
} }
} }
...@@ -106,12 +106,12 @@ impl VisitMut for DebugInstantStackPass { ...@@ -106,12 +106,12 @@ impl VisitMut for DebugInstantStackPass {
for item in items.iter() { for item in items.iter() {
match item { match item {
// `export const unstable_instant = ...` // `export const instant = ...`
ModuleItem::ModuleDecl(ModuleDecl::ExportDecl(export_decl)) => { ModuleItem::ModuleDecl(ModuleDecl::ExportDecl(export_decl)) => {
if let Decl::Var(var_decl) = &export_decl.decl { if let Decl::Var(var_decl) = &export_decl.decl {
for decl in &var_decl.decls { for decl in &var_decl.decls {
if let Pat::Ident(ident) = &decl.name if let Pat::Ident(ident) = &decl.name
&& ident.id.sym == "unstable_instant" && ident.id.sym == "instant"
&& let Some(init) = &decl.init && let Some(init) = &decl.init
{ {
self.instant_export_span = Some(init.span()); self.instant_export_span = Some(init.span());
...@@ -119,13 +119,13 @@ impl VisitMut for DebugInstantStackPass { ...@@ -119,13 +119,13 @@ impl VisitMut for DebugInstantStackPass {
} }
} }
} }
// `export { unstable_instant }` or `export { x as unstable_instant }` // `export { instant }` or `export { x as instant }`
// with or without `from '...'` // with or without `from '...'`
ModuleItem::ModuleDecl(ModuleDecl::ExportNamed(named)) => { ModuleItem::ModuleDecl(ModuleDecl::ExportNamed(named)) => {
for specifier in &named.specifiers { for specifier in &named.specifiers {
if let Some((_exported, orig)) = get_instant_specifier_names(specifier) { if let Some((_exported, orig)) = get_instant_specifier_names(specifier) {
if named.src.is_some() { if named.src.is_some() {
// Re-export: `export { unstable_instant } from './config'` // Re-export: `export { instant } from './config'`
// Point at the export specifier itself // Point at the export specifier itself
self.instant_export_span = Some(specifier.span()); self.instant_export_span = Some(specifier.span());
} else { } else {
...@@ -156,7 +156,7 @@ impl VisitMut for DebugInstantStackPass { ...@@ -156,7 +156,7 @@ impl VisitMut for DebugInstantStackPass {
} }
let mut cons = quote!( let mut cons = quote!(
"function unstable_instant() { "function instant() {
const error = $new_error const error = $new_error
error.name = 'Instant Validation' error.name = 'Instant Validation'
return error return error
...@@ -165,7 +165,7 @@ impl VisitMut for DebugInstantStackPass { ...@@ -165,7 +165,7 @@ impl VisitMut for DebugInstantStackPass {
); );
// Patch source_span onto the Function // 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 { if let Expr::Fn(f) = &mut cons {
f.function.span = source_span; f.function.span = source_span;
} }
......
...@@ -956,7 +956,7 @@ impl ReactServerComponentValidator { ...@@ -956,7 +956,7 @@ impl ReactServerComponentValidator {
), ),
); );
} }
"unstable_instant" if !self.cache_components_enabled => { "instant" if !self.cache_components_enabled => {
possibly_invalid_exports.insert( possibly_invalid_exports.insert(
export_name.clone(), export_name.clone(),
( (
......
export const unstable_instant = { export const instant = {
prefetch: 'static' prefetch: 'static'
}; };
export default function Page() { export default function Page() {
......
export const unstable_instant = { prefetch: 'static' } export const instant = { prefetch: 'static' }
export default function Page() { export default function Page() {
return <div>Hello</div> return <div>Hello</div>
......
export const unstable_instant = { export const instant = {
prefetch: 'static' prefetch: 'static'
}; };
export default function Page() { export default function Page() {
......
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] ,-[input.js:1:1]
1 | export const unstable_instant = { prefetch: 'static' } 1 | export const instant = { prefetch: 'static' }
: ^^^^^^^^^^^^^^^^ : ^^^^^^^
`---- `----
export const unstable_instant = { prefetch: 'static' } export const instant = { prefetch: 'static' }
export default function Page() { export default function Page() {
return <div>Hello</div> return <div>Hello</div>
......
const instant = { prefetch: 'static' } const instantConfig = { prefetch: 'static' }
export { instant as unstable_instant } export { instantConfig as instant }
export default function Page() { export default function Page() {
return <div>Hello</div> return <div>Hello</div>
......
const instant = { const instantConfig = {
prefetch: 'static' prefetch: 'static'
}; };
export { instant as unstable_instant }; export { instantConfig as instant };
export default function Page() { export default function Page() {
return <div>Hello</div>; return <div>Hello</div>;
} }
export const __debugCreateInstantConfigStack = process.env.NODE_ENV !== 'production' ? function unstable_instant() { export const __debugCreateInstantConfigStack = process.env.NODE_ENV !== 'production' ? function instant() {
const error = new Error(' '); const error = new Error(' ');
error.name = 'Instant Validation'; error.name = 'Instant Validation';
return error; return error;
......
{"version":3,"sources":["input.js"],"sourcesContent":["const instant = { prefetch: 'static' }\nexport { instant as unstable_instant }\n\nexport default function Page() {\n return <div>Hello</div>\n}\n"],"names":[],"mappings":"AAAA,MAAM,UAAU;IAAE,UAAU;AAAS;AACrC,SAAS,WAAW,gBAAgB,GAAE;AAEtC,eAAe,SAAS;IACtB,QAAQ,IAAI,KAAK,EAAE;AACrB;uFALgB;kBAAA"} {"version":3,"sources":["input.js"],"sourcesContent":["const instantConfig = { prefetch: 'static' }\nexport { instantConfig as instant }\n\nexport default function Page() {\n return <div>Hello</div>\n}\n"],"names":[],"mappings":"AAAA,MAAM,gBAAgB;IAAE,UAAU;AAAS;AAC3C,SAAS,iBAAiB,OAAO,GAAE;AAEnC,eAAe,SAAS;IACtB,QAAQ,IAAI,KAAK,EAAE;AACrB;uFALsB;kBAAA"}
const _instant = { prefetch: 'static' } const _instant = { prefetch: 'static' }
const instant = _instant const instantConfig = _instant
export { instant as unstable_instant } export { instantConfig as instant }
export default function Page() { export default function Page() {
return <div>Hello</div> return <div>Hello</div>
......
const _instant = { const _instant = {
prefetch: 'static' prefetch: 'static'
}; };
const instant = _instant; const instantConfig = _instant;
export { instant as unstable_instant }; export { instantConfig as instant };
export default function Page() { export default function Page() {
return <div>Hello</div>; return <div>Hello</div>;
} }
export const __debugCreateInstantConfigStack = process.env.NODE_ENV !== 'production' ? function unstable_instant() { export const __debugCreateInstantConfigStack = process.env.NODE_ENV !== 'production' ? function instant() {
const error = new Error(' '); const error = new Error(' ');
error.name = 'Instant Validation'; error.name = 'Instant Validation';
return error; return error;
......
{"version":3,"sources":["input.js"],"sourcesContent":["const _instant = { prefetch: 'static' }\nconst instant = _instant\nexport { instant as unstable_instant }\n\nexport default function Page() {\n return <div>Hello</div>\n}\n"],"names":[],"mappings":"AAAA,MAAM,WAAW;IAAE,UAAU;AAAS;AACtC,MAAM,UAAU;AAChB,SAAS,WAAW,gBAAgB,GAAE;AAEtC,eAAe,SAAS;IACtB,QAAQ,IAAI,KAAK,EAAE;AACrB;uFALgB;kBAAA"} {"version":3,"sources":["input.js"],"sourcesContent":["const _instant = { prefetch: 'static' }\nconst instantConfig = _instant\nexport { instantConfig as instant }\n\nexport default function Page() {\n return <div>Hello</div>\n}\n"],"names":[],"mappings":"AAAA,MAAM,WAAW;IAAE,UAAU;AAAS;AACtC,MAAM,gBAAgB;AACtB,SAAS,iBAAiB,OAAO,GAAE;AAEnC,eAAe,SAAS;IACtB,QAAQ,IAAI,KAAK,EAAE;AACrB;uFALsB;kBAAA"}
export const unstable_instant = { prefetch: 'static' } export const instant = { prefetch: 'static' }
export default function Page() { export default function Page() {
return <div>Hello</div> return <div>Hello</div>
......
export const unstable_instant = { export const instant = {
prefetch: 'static' prefetch: 'static'
}; };
export default function Page() { export default function Page() {
return <div>Hello</div>; return <div>Hello</div>;
} }
export const __debugCreateInstantConfigStack = process.env.NODE_ENV !== 'production' ? function unstable_instant() { export const __debugCreateInstantConfigStack = process.env.NODE_ENV !== 'production' ? function instant() {
const error = new Error(' '); const error = new Error(' ');
error.name = 'Instant Validation'; error.name = 'Instant Validation';
return error; return error;
......
{"version":3,"sources":["input.js"],"sourcesContent":["export const unstable_instant = { prefetch: 'static' }\n\nexport default function Page() {\n return <div>Hello</div>\n}\n"],"names":[],"mappings":"AAAA,OAAO,MAAM,mBAAmB;IAAE,UAAU;AAAS,EAAC;AAEtD,eAAe,SAAS;IACtB,QAAQ,IAAI,KAAK,EAAE;AACrB;uFAJgC;kBAAA"} {"version":3,"sources":["input.js"],"sourcesContent":["export const instant = { prefetch: 'static' }\n\nexport default function Page() {\n return <div>Hello</div>\n}\n"],"names":[],"mappings":"AAAA,OAAO,MAAM,UAAU;IAAE,UAAU;AAAS,EAAC;AAE7C,eAAe,SAAS;IACtB,QAAQ,IAAI,KAAK,EAAE;AACrB;uFAJuB;kBAAA"}
const unstable_instant = { prefetch: 'static' } const instant = { prefetch: 'static' }
export { unstable_instant } export { instant }
export default function Page() { export default function Page() {
return <div>Hello</div> return <div>Hello</div>
......
const unstable_instant = { const instant = {
prefetch: 'static' prefetch: 'static'
}; };
export { unstable_instant }; export { instant };
export default function Page() { export default function Page() {
return <div>Hello</div>; return <div>Hello</div>;
} }
export const __debugCreateInstantConfigStack = process.env.NODE_ENV !== 'production' ? function unstable_instant() { export const __debugCreateInstantConfigStack = process.env.NODE_ENV !== 'production' ? function instant() {
const error = new Error(' '); const error = new Error(' ');
error.name = 'Instant Validation'; error.name = 'Instant Validation';
return error; return error;
......
{"version":3,"sources":["input.js"],"sourcesContent":["const unstable_instant = { prefetch: 'static' }\nexport { unstable_instant }\n\nexport default function Page() {\n return <div>Hello</div>\n}\n"],"names":[],"mappings":"AAAA,MAAM,mBAAmB;IAAE,UAAU;AAAS;AAC9C,SAAS,gBAAgB,GAAE;AAE3B,eAAe,SAAS;IACtB,QAAQ,IAAI,KAAK,EAAE;AACrB;uFALyB;kBAAA"} {"version":3,"sources":["input.js"],"sourcesContent":["const instant = { prefetch: 'static' }\nexport { instant }\n\nexport default function Page() {\n return <div>Hello</div>\n}\n"],"names":[],"mappings":"AAAA,MAAM,UAAU;IAAE,UAAU;AAAS;AACrC,SAAS,OAAO,GAAE;AAElB,eAAe,SAAS;IACtB,QAAQ,IAAI,KAAK,EAAE;AACrB;uFALgB;kBAAA"}
export { unstable_instant } from './config' export { instant } from './config'
export default function Page() { export default function Page() {
return <div>Hello</div> return <div>Hello</div>
......
export { unstable_instant } from './config'; export { instant } from './config';
export default function Page() { export default function Page() {
return <div>Hello</div>; return <div>Hello</div>;
} }
export const __debugCreateInstantConfigStack = process.env.NODE_ENV !== 'production' ? function unstable_instant() { export const __debugCreateInstantConfigStack = process.env.NODE_ENV !== 'production' ? function instant() {
const error = new Error(' '); const error = new Error(' ');
error.name = 'Instant Validation'; error.name = 'Instant Validation';
return error; return error;
......
{"version":3,"sources":["input.js"],"sourcesContent":["export { unstable_instant } from './config'\n\nexport default function Page() {\n return <div>Hello</div>\n}\n"],"names":[],"mappings":"AAAA,SAAS,gBAAgB,QAAQ,WAAU;AAE3C,eAAe,SAAS;IACtB,QAAQ,IAAI,KAAK,EAAE;AACrB;uFAJS;kBAAA"} {"version":3,"sources":["input.js"],"sourcesContent":["export { instant } from './config'\n\nexport default function Page() {\n return <div>Hello</div>\n}\n"],"names":[],"mappings":"AAAA,SAAS,OAAO,QAAQ,WAAU;AAElC,eAAe,SAAS;IACtB,QAAQ,IAAI,KAAK,EAAE;AACrB;uFAJS;kBAAA"}
...@@ -15,7 +15,7 @@ related: ...@@ -15,7 +15,7 @@ related:
With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, `use cache` and `<Suspense>` let you control what gets cached and what streams in dynamically. When these are in the right place, client-side navigations are instant. With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, `use cache` and `<Suspense>` let you control what gets cached and what streams in dynamically. When these are in the right place, client-side navigations are instant.
The [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) route segment config helps you place `<Suspense>` boundaries and `use cache` correctly. Add it to any page or layout and Next.js will check during development that navigating to that route produces an instant [static shell](/docs/app/glossary#static-shell). The [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) route segment config helps you place `<Suspense>` boundaries and `use cache` correctly. Add it to any page or layout and Next.js will check during development that navigating to that route produces an instant [static shell](/docs/app/glossary#static-shell).
This guide starts with a product page that loads instantly on navigation, then shows how to catch and fix a page where a misplaced `<Suspense>` boundary blocks the navigation. Nothing visible changes until the server finishes rendering. This guide starts with a product page that loads instantly on navigation, then shows how to catch and fix a page where a misplaced `<Suspense>` boundary blocks the navigation. Nothing visible changes until the server finishes rendering.
...@@ -34,7 +34,7 @@ A product page at `/store/[slug]` that fetches two pieces of data: product detai ...@@ -34,7 +34,7 @@ A product page at `/store/[slug]` that fetches two pieces of data: product detai
import { Suspense } from 'react' import { Suspense } from 'react'
import { db } from '@/lib/db' import { db } from '@/lib/db'
export const unstable_instant = true export const instant = true
export default function ProductPage(props: PageProps<'/store/[slug]'>) { export default function ProductPage(props: PageProps<'/store/[slug]'>) {
return ( return (
...@@ -74,7 +74,7 @@ async function Inventory({ params }: { params: Params }) { ...@@ -74,7 +74,7 @@ async function Inventory({ params }: { params: Params }) {
} }
``` ```
The [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) export tells Next.js to check that navigating to this page from any other page in your app is instant. It does this during development. If a component would delay the transition (for example, by fetching uncached data without a local `<Suspense>` boundary), the error overlay tells you which one and suggests a fix. The [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) export tells Next.js to check that navigating to this page from any other page in your app is instant. It does this during development. If a component would delay the transition (for example, by fetching uncached data without a local `<Suspense>` boundary), the error overlay tells you which one and suggests a fix.
Validation runs automatically on every page load using the real request from your browser, so dynamic params like `[slug]` are checked against actual values as you navigate. Validation runs automatically on every page load using the real request from your browser, so dynamic params like `[slug]` are checked against actual values as you navigate.
...@@ -190,12 +190,12 @@ You can see this with the DevTools. Try a **page load**: the root `<Suspense>` c ...@@ -190,12 +190,12 @@ You can see this with the DevTools. Try a **page load**: the root `<Suspense>` c
### Step 1: Add instant validation ### Step 1: Add instant validation
Add an `unstable_instant` export to the page to surface the problem: Add an `instant` export to the page to surface the problem:
```tsx filename="app/shop/[slug]/page.tsx" highlight={3} ```tsx filename="app/shop/[slug]/page.tsx" highlight={3}
import { db } from '@/lib/db' import { db } from '@/lib/db'
export const unstable_instant = true export const instant = true
export default async function ProductPage(props: PageProps<'/shop/[slug]'>) { export default async function ProductPage(props: PageProps<'/shop/[slug]'>) {
const { slug } = await props.params const { slug } = await props.params
...@@ -257,7 +257,7 @@ The page passes `params` to each component and wraps them with `<Suspense>`: ...@@ -257,7 +257,7 @@ The page passes `params` to each component and wraps them with `<Suspense>`:
import { Suspense } from 'react' import { Suspense } from 'react'
import { db } from '@/lib/db' import { db } from '@/lib/db'
export const unstable_instant = true export const instant = true
export default function ProductPage(props: PageProps<'/shop/[slug]'>) { export default function ProductPage(props: PageProps<'/shop/[slug]'>) {
return ( return (
...@@ -278,7 +278,7 @@ Validation passes. Open the DevTools and try a client navigation. The product na ...@@ -278,7 +278,7 @@ Validation passes. Open the DevTools and try a client navigation. The product na
<details> <details>
<summary>How validation simulates different navigations</summary> <summary>How validation simulates different navigations</summary>
When you add `unstable_instant` to a route, Next.js checks both the initial page load and client navigations at different points in the route hierarchy. When you add `instant` to a route, Next.js checks both the initial page load and client navigations at different points in the route hierarchy.
For a route like `/shop/[slug]`, validation checks: For a route like `/shop/[slug]`, validation checks:
...@@ -294,7 +294,7 @@ Each case is validated independently. A `<Suspense>` boundary that covers one na ...@@ -294,7 +294,7 @@ Each case is validated independently. A `<Suspense>` boundary that covers one na
Not every layout or page can be instant. A dashboard layout that reads cookies and fetches user-specific data might be too dynamic for the first visit. You can set `instant = false` on any layout or page to exempt it from validation: Not every layout or page can be instant. A dashboard layout that reads cookies and fetches user-specific data might be too dynamic for the first visit. You can set `instant = false` on any layout or page to exempt it from validation:
```tsx filename="app/dashboard/layout.tsx" ```tsx filename="app/dashboard/layout.tsx"
export const unstable_instant = false export const instant = false
``` ```
This tells validation: navigating to `/dashboard` from outside does not need to be instant, but sibling navigations within it still do. Navigating from `/dashboard/a` to `/dashboard/b` can still be checked by adding `instant` to the page segments under `/dashboard`. This tells validation: navigating to `/dashboard` from outside does not need to be instant, but sibling navigations within it still do. Navigating from `/dashboard/a` to `/dashboard/b` can still be checked by adding `instant` to the page segments under `/dashboard`.
......
...@@ -12,20 +12,20 @@ related: ...@@ -12,20 +12,20 @@ related:
- app/api-reference/directives/use-cache - app/api-reference/directives/use-cache
--- ---
The `unstable_instant` route segment config controls how Next.js validates whether a navigation into this segment would produce an instant UI. The `instant` route segment config controls how Next.js validates whether a navigation into this segment would produce an instant UI.
Next.js uses prefetching to preload navigations for all in-app links on the current page. However, client-side data fetching or partially prerendered results from the server can lead to navigations that don't update the UI immediately. To help you build fast-feeling navigations, `unstable_instant` lets you tell Next.js what to expect from navigations through the configured segment. For instance, you can indicate that navigations into this segment should produce a UI that renders instantly without waiting on any externally loaded data. You can also indicate that navigations aren't expected to be instant. Next.js uses prefetching to preload navigations for all in-app links on the current page. However, client-side data fetching or partially prerendered results from the server can lead to navigations that don't update the UI immediately. To help you build fast-feeling navigations, `instant` lets you tell Next.js what to expect from navigations through the configured segment. For instance, you can indicate that navigations into this segment should produce a UI that renders instantly without waiting on any externally loaded data. You can also indicate that navigations aren't expected to be instant.
When a segment is configured to expect an instant UI, Next.js surfaces any code in your application that would block the navigation from updating the UI immediately. See the [Instant Navigation guide](/docs/app/guides/instant-navigation) for an end-to-end walkthrough. When a segment is configured to expect an instant UI, Next.js surfaces any code in your application that would block the navigation from updating the UI immediately. See the [Instant Navigation guide](/docs/app/guides/instant-navigation) for an end-to-end walkthrough.
> **Good to know**: > **Good to know**:
> >
> - The `unstable_instant` export only works when [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled. > - The `instant` export only works when [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled.
> - `unstable_instant` cannot be used in Client Components. It will throw an error. > - `instant` cannot be used in Client Components. It will throw an error.
> - Next.js does not perform prefetches in development, so navigations may not feel as instant as they will in production. Validation reflects what will happen during `next start`, where prefetching is enabled. > - Next.js does not perform prefetches in development, so navigations may not feel as instant as they will in production. Validation reflects what will happen during `next start`, where prefetching is enabled.
```tsx filename="layout.tsx | page.tsx" switcher ```tsx filename="layout.tsx | page.tsx" switcher
export const unstable_instant = true export const instant = true
export default function Page() { export default function Page() {
return <div>...</div> return <div>...</div>
...@@ -33,7 +33,7 @@ export default function Page() { ...@@ -33,7 +33,7 @@ export default function Page() {
``` ```
```jsx filename="layout.js | page.js" switcher ```jsx filename="layout.js | page.js" switcher
export const unstable_instant = true export const instant = true
export default function Page() { export default function Page() {
return <div>...</div> return <div>...</div>
...@@ -53,7 +53,7 @@ The export accepts: ...@@ -53,7 +53,7 @@ The export accepts:
Sets the severity at which validation runs for this segment. Sets the severity at which validation runs for this segment.
```tsx filename="page.tsx" ```tsx filename="page.tsx"
export const unstable_instant = { export const instant = {
level: 'warning', level: 'warning',
} }
``` ```
...@@ -62,41 +62,41 @@ export const unstable_instant = { ...@@ -62,41 +62,41 @@ export const unstable_instant = {
In the future a validation level that supports validation during build will be supported. Unless you are enabling experimental validation modes there is no need to specify level since the only level available is `"warning"`. In the future a validation level that supports validation during build will be supported. Unless you are enabling experimental validation modes there is no need to specify level since the only level available is `"warning"`.
When `level` is omitted (or `unstable_instant = true` is used), the segment is validated at whatever level is configured globally — see [Configuring validation defaults](#configuring-validation-defaults). When `level` is omitted (or `instant = true` is used), the segment is validated at whatever level is configured globally — see [Configuring validation defaults](#configuring-validation-defaults).
### Disabling instant ### Disabling instant
Set `false` on a layout or page to indicate that this segment is allowed to block when navigating to it. Set `false` on a layout or page to indicate that this segment is allowed to block when navigating to it.
This is useful when a deeper page should be instant but an ancestor can't be. For instance, if a shared layout cannot load instantly but you still want to assert that pages beneath this layout can be navigated to instantly, you can ensure that the pages have `unstable_instant = true` while the shared layout has `unstable_instant = false`. This is useful when a deeper page should be instant but an ancestor can't be. For instance, if a shared layout cannot load instantly but you still want to assert that pages beneath this layout can be navigated to instantly, you can ensure that the pages have `instant = true` while the shared layout has `instant = false`.
```tsx filename="app/tabs/layout.tsx" ```tsx filename="app/tabs/layout.tsx"
export const unstable_instant = false export const instant = false
``` ```
```tsx filename="app/tabs/[tab]/page.tsx" ```tsx filename="app/tabs/[tab]/page.tsx"
export const unstable_instant = true export const instant = true
``` ```
Navigations from outside into a tab are allowed to block at the layout. Navigations between tabs are validated for instant UI. Navigations from outside into a tab are allowed to block at the layout. Navigations between tabs are validated for instant UI.
You don't need to add `false` to ancestors of an instant page just because they do something blocking — a higher-up `unstable_instant = true` doesn't force its descendants to validate, and leaving an ancestor unconfigured is fine. Reach for `false` only when you've configured a deeper page as instant and need to exempt navigations that pass through a blocking ancestor. You don't need to add `false` to ancestors of an instant page just because they do something blocking — a higher-up `instant = true` doesn't force its descendants to validate, and leaving an ancestor unconfigured is fine. Reach for `false` only when you've configured a deeper page as instant and need to exempt navigations that pass through a blocking ancestor.
### Disabling static shell validation ### Disabling static shell validation
Cache Components also validates that each page in your app produces a non-empty static shell at prerender time. To opt a route out of this validation, ensure the highest `unstable_instant` config in the route's tree is `false` — a `false` higher in the tree takes precedence over any deeper `true` for the static-shell check. Cache Components also validates that each page in your app produces a non-empty static shell at prerender time. To opt a route out of this validation, ensure the highest `instant` config in the route's tree is `false` — a `false` higher in the tree takes precedence over any deeper `true` for the static-shell check.
Setting `false` on the root layout disables static shell validation for the entire app. Place the `false` as low as possible — only as high as needed to cover the routes you want to opt out — so the rest of the app keeps validating. Setting `false` on the root layout disables static shell validation for the entire app. Place the `false` as low as possible — only as high as needed to cover the routes you want to opt out — so the rest of the app keeps validating.
## How validation works ## How validation works
`unstable_instant` triggers validation at every shared layout boundary in the route. Validation runs during development (on page loads and HMR updates) and surfaces errors in the dev error overlay. `instant` triggers validation at every shared layout boundary in the route. Validation runs during development (on page loads and HMR updates) and surfaces errors in the dev error overlay.
Each error identifies the component that would block navigation. The fix is usually to cache the data with `use cache` or wrap it in a `<Suspense>` boundary. Each error identifies the component that would block navigation. The fix is usually to cache the data with `use cache` or wrap it in a `<Suspense>` boundary.
## Configuring validation defaults ## Configuring validation defaults
By default, only segments that explicitly export `unstable_instant` are validated. The `experimental.instantInsights.validationLevel` config opts every Page and Default segment into validation at once, without needing to repeat `unstable_instant` on each route. By default, only segments that explicitly export `instant` are validated. The `experimental.instantInsights.validationLevel` config opts every Page and Default segment into validation at once, without needing to repeat `instant` on each route.
```js filename="next.config.js" ```js filename="next.config.js"
module.exports = { module.exports = {
...@@ -110,15 +110,15 @@ module.exports = { ...@@ -110,15 +110,15 @@ module.exports = {
The supported levels are: The supported levels are:
- **`'manual-warning'`** _(framework default)_: Only segments with an explicit `unstable_instant` are validated, at warning level (dev only). - **`'manual-warning'`** _(framework default)_: Only segments with an explicit `instant` are validated, at warning level (dev only).
- **`'warning'`**: Every Page and Default segment is implicitly validated at warning level (dev only). - **`'warning'`**: Every Page and Default segment is implicitly validated at warning level (dev only).
Setting `unstable_instant = false` on a segment opts it out of validation entirely. Setting `instant = false` on a segment opts it out of validation entirely.
> **Good to know**: > **Good to know**:
> >
> - The framework default may change in future versions to opt users into higher levels of validation. Because this feature is experimental, that change is not considered a breaking change. To pin a specific behavior, set `validationLevel` explicitly. > - The framework default may change in future versions to opt users into higher levels of validation. Because this feature is experimental, that change is not considered a breaking change. To pin a specific behavior, set `validationLevel` explicitly.
> - Framework-synthesized error routes (`/_global-error`, `/_not-found`) are excluded from implicit validation. To validate them, opt in explicitly with `unstable_instant`. > - Framework-synthesized error routes (`/_global-error`, `/_not-found`) are excluded from implicit validation. To validate them, opt in explicitly with `instant`.
## Inspecting loading states ## Inspecting loading states
...@@ -163,11 +163,11 @@ type InstantConfig = ...@@ -163,11 +163,11 @@ type InstantConfig =
level?: 'warning' level?: 'warning'
} }
export const unstable_instant: InstantConfig = true export const instant: InstantConfig = true
``` ```
## Version History ## Version History
| Version | Changes | | Version | Changes |
| --------- | ------------------------------------------------------------ | | --------- | --------------------------------------------------- |
| `v16.x.x` | `unstable_instant` export introduced (Cache Components only) | | `v16.x.x` | `instant` export introduced (Cache Components only) |
...@@ -12,7 +12,7 @@ related: ...@@ -12,7 +12,7 @@ related:
The `prefetch` route segment config controls how a segment is prefetched during client-side navigation. The default (`'auto'`) lets Next.js manage the strategy on your behalf — today that always means a static prefetch. The other options let you declare which prefetch behavior is appropriate for the segment. Use them with care, since they can affect both navigation latency and prefetch cost. The `prefetch` route segment config controls how a segment is prefetched during client-side navigation. The default (`'auto'`) lets Next.js manage the strategy on your behalf — today that always means a static prefetch. The other options let you declare which prefetch behavior is appropriate for the segment. Use them with care, since they can affect both navigation latency and prefetch cost.
When you do set this export, consider pairing it with [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) so validation can confirm that navigations to this segment actually produce an instant UI from the prefetched data. This is especially important for runtime prefetching. When you do set this export, consider pairing it with [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) so validation can confirm that navigations to this segment actually produce an instant UI from the prefetched data. This is especially important for runtime prefetching.
> **Good to know**: > **Good to know**:
> >
...@@ -41,7 +41,7 @@ export default function Page() { ...@@ -41,7 +41,7 @@ export default function Page() {
Lets Next.js manage prefetching for this segment. Today this always means a static prefetch — to permit runtime prefetching, opt in explicitly with [`'allow-runtime'`](#allow-runtime). Lets Next.js manage prefetching for this segment. Today this always means a static prefetch — to permit runtime prefetching, opt in explicitly with [`'allow-runtime'`](#allow-runtime).
A future release will use [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) validation to choose between static and runtime prefetching automatically. Leaving the default in place means your app will pick up that improvement without code changes. A future release will use [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) validation to choose between static and runtime prefetching automatically. Leaving the default in place means your app will pick up that improvement without code changes.
You typically don't need to set this explicitly — omitting the export has the same effect. You typically don't need to set this explicitly — omitting the export has the same effect.
...@@ -57,7 +57,7 @@ export const prefetch = 'allow-runtime' ...@@ -57,7 +57,7 @@ export const prefetch = 'allow-runtime'
### `'force-static'` ### `'force-static'`
Always prefetch this segment statically, even if it has not been validated with `unstable_instant`. Use this when you know the segment produces a valid static shell but do not want to set up instant validation. Always prefetch this segment statically, even if it has not been validated with `instant`. Use this when you know the segment produces a valid static shell but do not want to set up instant validation.
### `'force-disabled'` ### `'force-disabled'`
......
...@@ -216,12 +216,12 @@ export default function RootLayout({ children }) { ...@@ -216,12 +216,12 @@ export default function RootLayout({ children }) {
} }
``` ```
Alternatively, opt the segment out of instant-navigation validation with [`unstable_instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant). The route renders on every request and the navigation blocks until the render completes: Alternatively, opt the segment out of instant-navigation validation with [`instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant). The route renders on every request and the navigation blocks until the render completes:
```tsx filename="app/dashboard/layout.tsx" highlight={1,3} ```tsx filename="app/dashboard/layout.tsx" highlight={1,3}
import { cookies } from 'next/headers' import { cookies } from 'next/headers'
export const unstable_instant = false export const instant = false
export async function generateViewport() { export async function generateViewport() {
const cookieJar = await cookies() const cookieJar = await cookies()
...@@ -235,7 +235,7 @@ export default function DashboardLayout({ children }) { ...@@ -235,7 +235,7 @@ export default function DashboardLayout({ children }) {
} }
``` ```
Setting `unstable_instant = false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Next.js encountered runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime) for the full set of fix options, trade-offs, and the subtree-wide opt-out. Setting `instant = false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Next.js encountered runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime) for the full set of fix options, trade-offs, and the subtree-wide opt-out.
> **Good to know**: Use [multiple root layouts](/docs/app/api-reference/file-conventions/layout#root-layout) to isolate fully dynamic viewport to specific routes, while still letting other routes in your application generate a static shell. > **Good to know**: Use [multiple root layouts](/docs/app/api-reference/file-conventions/layout#root-layout) to isolate fully dynamic viewport to specific routes, while still letting other routes in your application generate a static shell.
......
...@@ -36,7 +36,7 @@ Server-side request-bound reads ([`cookies()`](/docs/app/api-reference/functions ...@@ -36,7 +36,7 @@ Server-side request-bound reads ([`cookies()`](/docs/app/api-reference/functions
<FixOption <FixOption
group="block" group="block"
href="#allow-blocking-route" href="#allow-blocking-route"
prompt={`Add "export const unstable_instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally request-time before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request, so navigations to it block until the render completes.`} prompt={`Add "export const instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally request-time before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request, so navigations to it block until the render completes.`}
title="Allow blocking route" title="Allow blocking route"
> >
Opt the segment out of instant-navigation validation. The route renders on Opt the segment out of instant-navigation validation. The route renders on
...@@ -226,7 +226,7 @@ The list of params is decided at build time. See [`generateStaticParams`](/docs/ ...@@ -226,7 +226,7 @@ The list of params is decided at build time. See [`generateStaticParams`](/docs/
## Allow blocking route ## Allow blocking route
Choose this fix when the route renders per-request and there's no useful static shell. Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes. Choose this fix when the route renders per-request and there's no useful static shell. Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes.
### Patterns ### Patterns
...@@ -235,7 +235,7 @@ Choose this fix when the route renders per-request and there's no useful static ...@@ -235,7 +235,7 @@ Choose this fix when the route renders per-request and there's no useful static
Add the export to the page that triggered the error. Only that route blocks. Add the export to the page that triggered the error. Only that route blocks.
```jsx filename="app/dashboard/page.js" ```jsx filename="app/dashboard/page.js"
export const unstable_instant = false export const instant = false
export default function Page() { export default function Page() {
return <Dashboard /> return <Dashboard />
...@@ -246,10 +246,10 @@ Learn more: [Ensuring instant navigations](/docs/app/guides/instant-navigation). ...@@ -246,10 +246,10 @@ Learn more: [Ensuring instant navigations](/docs/app/guides/instant-navigation).
#### Opt the layout out #### Opt the layout out
When the shared layout itself can't ship instantly (it reads URL data of its own that has no meaningful fallback), set [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout. The layout and every route in the subtree are exempted from instant-navigation validation. When the shared layout itself can't ship instantly (it reads URL data of its own that has no meaningful fallback), set [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout. This allows that layout segment to block while descendant segments remain independently validated.
```jsx filename="app/dashboard/layout.js" ```jsx filename="app/dashboard/layout.js"
export const unstable_instant = false export const instant = false
export default function DashboardLayout({ children }) { export default function DashboardLayout({ children }) {
return <DashboardShell>{children}</DashboardShell> return <DashboardShell>{children}</DashboardShell>
...@@ -271,16 +271,16 @@ Navigations to this route are not instant. The user waits for the full server re ...@@ -271,16 +271,16 @@ Navigations to this route are not instant. The user waits for the full server re
### Gotchas ### Gotchas
- Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Don't want this validation?](#dont-want-this-validation) for the subtree-wide opt-out. - Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Don't want this validation?](#dont-want-this-validation) for the subtree-wide opt-out.
- This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error. - This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error.
## Don't want this validation? ## Don't want this validation?
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -180,9 +180,9 @@ The user sees the placeholder briefly before the real value. For interactions th ...@@ -180,9 +180,9 @@ The user sees the placeholder briefly before the real value. For interactions th
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -216,9 +216,9 @@ The first paint shows the SSR fallback (often `null`), and the value appears onl ...@@ -216,9 +216,9 @@ The first paint shows the SSR fallback (often `null`), and the value appears onl
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -224,9 +224,9 @@ Learn more: [`Date.now()` during prerendering](/docs/messages/blocking-prerender ...@@ -224,9 +224,9 @@ Learn more: [`Date.now()` during prerendering](/docs/messages/blocking-prerender
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -274,9 +274,9 @@ Learn more: [`performance.now()`](https://developer.mozilla.org/en-US/docs/Web/A ...@@ -274,9 +274,9 @@ Learn more: [`performance.now()`](https://developer.mozilla.org/en-US/docs/Web/A
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -36,7 +36,7 @@ This error can also appear during a client-side navigation when the data access ...@@ -36,7 +36,7 @@ This error can also appear during a client-side navigation when the data access
<FixOption <FixOption
group="block" group="block"
href="#allow-blocking-route" href="#allow-blocking-route"
prompt={`Add "export const unstable_instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally request-time before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request, so navigations to it block until the render completes.`} prompt={`Add "export const instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally request-time before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request, so navigations to it block until the render completes.`}
title="Allow blocking route" title="Allow blocking route"
> >
Opt this segment out of instant navigation. The route has no static shell and Opt this segment out of instant navigation. The route has no static shell and
...@@ -251,7 +251,7 @@ A useful rule: **push the boundary as low as possible** while keeping the fallba ...@@ -251,7 +251,7 @@ A useful rule: **push the boundary as low as possible** while keeping the fallba
## Allow blocking route ## Allow blocking route
Choose this fix when the route renders per-request and there's no useful static shell. Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes. Choose this fix when the route renders per-request and there's no useful static shell. Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes.
### Patterns ### Patterns
...@@ -260,7 +260,7 @@ Choose this fix when the route renders per-request and there's no useful static ...@@ -260,7 +260,7 @@ Choose this fix when the route renders per-request and there's no useful static
Add the export to the page that triggered the error. Only that route blocks. Add the export to the page that triggered the error. Only that route blocks.
```jsx filename="app/dashboard/page.js" ```jsx filename="app/dashboard/page.js"
export const unstable_instant = false export const instant = false
export default async function Page() { export default async function Page() {
const data = await getDashboard() const data = await getDashboard()
...@@ -272,10 +272,10 @@ Learn more: [Ensuring instant navigations](/docs/app/guides/instant-navigation). ...@@ -272,10 +272,10 @@ Learn more: [Ensuring instant navigations](/docs/app/guides/instant-navigation).
#### Opt the layout out #### Opt the layout out
When the shared layout itself can't ship instantly (it reads runtime data or uncached data of its own), set [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout. The layout and every route in the subtree are exempted from instant-navigation validation. When the shared layout itself can't ship instantly (it reads runtime data or uncached data of its own), set [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout. This allows that layout segment to block while descendant segments remain independently validated.
```jsx filename="app/dashboard/layout.js" ```jsx filename="app/dashboard/layout.js"
export const unstable_instant = false export const instant = false
export default function DashboardLayout({ children }) { export default function DashboardLayout({ children }) {
return <DashboardShell>{children}</DashboardShell> return <DashboardShell>{children}</DashboardShell>
...@@ -297,16 +297,16 @@ Navigations to this route are not instant. The user waits for the full server re ...@@ -297,16 +297,16 @@ Navigations to this route are not instant. The user waits for the full server re
### Gotchas ### Gotchas
- Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Don't want this validation?](#dont-want-this-validation) for the subtree-wide opt-out. - Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Don't want this validation?](#dont-want-this-validation) for the subtree-wide opt-out.
- This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error. - This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error.
## Don't want this validation? ## Don't want this validation?
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -155,9 +155,9 @@ The metadata and the dynamic marker run on every request, so the route cannot be ...@@ -155,9 +155,9 @@ The metadata and the dynamic marker run on every request, so the route cannot be
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -146,9 +146,9 @@ The metadata and the dynamic marker run on every request, so the route cannot be ...@@ -146,9 +146,9 @@ The metadata and the dynamic marker run on every request, so the route cannot be
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -173,9 +173,9 @@ The user sees the placeholder briefly before the real value. For interactions th ...@@ -173,9 +173,9 @@ The user sees the placeholder briefly before the real value. For interactions th
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -194,9 +194,9 @@ The first paint shows the SSR fallback or initial state, and the random value ap ...@@ -194,9 +194,9 @@ The first paint shows the SSR fallback or initial state, and the random value ap
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -36,7 +36,7 @@ This error can also appear during a client-side navigation when the data access ...@@ -36,7 +36,7 @@ This error can also appear during a client-side navigation when the data access
<FixOption <FixOption
group="block" group="block"
href="#allow-blocking-route" href="#allow-blocking-route"
prompt={`Add "export const unstable_instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally request-time before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request, so navigations to it block until the render completes.`} prompt={`Add "export const instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally request-time before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request, so navigations to it block until the render completes.`}
title="Allow blocking route" title="Allow blocking route"
> >
Opt this segment out of instant navigation. The route has no static shell and Opt this segment out of instant navigation. The route has no static shell and
...@@ -237,7 +237,7 @@ The list of params is decided at build time. See [`generateStaticParams`](/docs/ ...@@ -237,7 +237,7 @@ The list of params is decided at build time. See [`generateStaticParams`](/docs/
## Allow blocking route ## Allow blocking route
Choose this fix when the route renders per-request and there's no useful static shell. Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes. Choose this fix when the route renders per-request and there's no useful static shell. Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes.
### Patterns ### Patterns
...@@ -246,7 +246,7 @@ Choose this fix when the route renders per-request and there's no useful static ...@@ -246,7 +246,7 @@ Choose this fix when the route renders per-request and there's no useful static
Add the export to the page that triggered the error. Only that route blocks. Add the export to the page that triggered the error. Only that route blocks.
```jsx filename="app/dashboard/page.js" ```jsx filename="app/dashboard/page.js"
export const unstable_instant = false export const instant = false
export default async function Page() { export default async function Page() {
const session = (await cookies()).get('session') const session = (await cookies()).get('session')
...@@ -258,10 +258,10 @@ Learn more: [Ensuring instant navigations](/docs/app/guides/instant-navigation). ...@@ -258,10 +258,10 @@ Learn more: [Ensuring instant navigations](/docs/app/guides/instant-navigation).
#### Opt the layout out #### Opt the layout out
When the shared layout itself can't ship instantly (it reads [`cookies()`](/docs/app/api-reference/functions/cookies) or [`headers()`](/docs/app/api-reference/functions/headers) of its own), set [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout. The layout and every route in the subtree are exempted from instant-navigation validation. When the shared layout itself can't ship instantly (it reads [`cookies()`](/docs/app/api-reference/functions/cookies) or [`headers()`](/docs/app/api-reference/functions/headers) of its own), set [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout. This allows that layout segment to block while descendant segments remain independently validated.
```jsx filename="app/dashboard/layout.js" ```jsx filename="app/dashboard/layout.js"
export const unstable_instant = false export const instant = false
export default function DashboardLayout({ children }) { export default function DashboardLayout({ children }) {
return <DashboardShell>{children}</DashboardShell> return <DashboardShell>{children}</DashboardShell>
...@@ -283,16 +283,16 @@ Navigations to this route are not instant. The user waits for the full server re ...@@ -283,16 +283,16 @@ Navigations to this route are not instant. The user waits for the full server re
### Gotchas ### Gotchas
- Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Don't want this validation?](#dont-want-this-validation) for the subtree-wide opt-out. - Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Don't want this validation?](#dont-want-this-validation) for the subtree-wide opt-out.
- This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error. - This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error.
## Don't want this validation? ## Don't want this validation?
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -24,7 +24,7 @@ Request-bound reads ([`cookies()`](/docs/app/api-reference/functions/cookies), [ ...@@ -24,7 +24,7 @@ Request-bound reads ([`cookies()`](/docs/app/api-reference/functions/cookies), [
<FixOption <FixOption
group="block" group="block"
href="#allow-blocking-route" href="#allow-blocking-route"
prompt={`Add "export const unstable_instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally fully dynamic before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request.`} prompt={`Add "export const instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally fully dynamic before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request.`}
title="Allow blocking route" title="Allow blocking route"
> >
Opt this segment out of instant navigation. The route renders on every request Opt this segment out of instant navigation. The route renders on every request
...@@ -72,7 +72,7 @@ Freshness depends on the cache configuration. The viewport stays the same until ...@@ -72,7 +72,7 @@ Freshness depends on the cache configuration. The viewport stays the same until
## Allow blocking route ## Allow blocking route
Choose this fix when the viewport data is genuinely uncacheable. Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes. Choose this fix when the viewport data is genuinely uncacheable. Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes.
Unlike page body content, viewport metadata can't be deferred behind [`<Suspense>`](https://react.dev/reference/react/Suspense) because it affects the initial HTML `<head>`. Making the viewport dynamic means the entire page navigation blocks. Unlike page body content, viewport metadata can't be deferred behind [`<Suspense>`](https://react.dev/reference/react/Suspense) because it affects the initial HTML `<head>`. Making the viewport dynamic means the entire page navigation blocks.
...@@ -80,12 +80,12 @@ Unlike page body content, viewport metadata can't be deferred behind [`<Suspense ...@@ -80,12 +80,12 @@ Unlike page body content, viewport metadata can't be deferred behind [`<Suspense
#### Opt the layout out #### Opt the layout out
Set [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout that defines `generateViewport`. The layout and every route in its subtree are exempted from instant-navigation validation. Apply this to the nested layout that owns the dynamic viewport, not the root layout, so the opt-out is scoped to the affected subtree. Set [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout that defines `generateViewport`. This allows that layout segment to block while descendant segments remain independently validated. Apply this to the nested layout that owns the dynamic viewport, not the root layout, so the opt-out is scoped to the affected segment.
```jsx filename="app/dashboard/layout.js" ```jsx filename="app/dashboard/layout.js"
import { db } from './db' import { db } from './db'
export const unstable_instant = false export const instant = false
export async function generateViewport() { export async function generateViewport() {
const { width, initialScale } = await db.query('viewport-config') const { width, initialScale } = await db.query('viewport-config')
...@@ -112,17 +112,17 @@ Navigations to this route are not instant. The user waits for the full server re ...@@ -112,17 +112,17 @@ Navigations to this route are not instant. The user waits for the full server re
### Gotchas ### Gotchas
- Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Don't want this validation?](#dont-want-this-validation) for the subtree-wide opt-out. - Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Don't want this validation?](#dont-want-this-validation) for the subtree-wide opt-out.
- This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error. - This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error.
- Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateViewport` and must be statically prerendered. [`unstable_instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) silences the validation error but does not let those routes through, so the build still fails when they prerender. If your root layout's `generateViewport` depends on request data, [Cache the viewport data](#cache-the-viewport-data) instead, or move to [`global-not-found.js`](/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateViewport`. - Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateViewport` and must be statically prerendered. [`instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) silences the validation error but does not let those routes through, so the build still fails when they prerender. If your root layout's `generateViewport` depends on request data, [Cache the viewport data](#cache-the-viewport-data) instead, or move to [`global-not-found.js`](/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateViewport`.
## Don't want this validation? ## Don't want this validation?
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -24,7 +24,7 @@ Uncached data accesses ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web ...@@ -24,7 +24,7 @@ Uncached data accesses ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web
<FixOption <FixOption
group="block" group="block"
href="#allow-blocking-route" href="#allow-blocking-route"
prompt={`Add "export const unstable_instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally fully dynamic before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request.`} prompt={`Add "export const instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally fully dynamic before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request.`}
title="Allow blocking route" title="Allow blocking route"
> >
Opt this segment out of instant navigation. The route renders on every request Opt this segment out of instant navigation. The route renders on every request
...@@ -70,7 +70,7 @@ Static viewport can't reflect per-request values like a user's preferred theme c ...@@ -70,7 +70,7 @@ Static viewport can't reflect per-request values like a user's preferred theme c
## Allow blocking route ## Allow blocking route
Choose this fix when the viewport genuinely requires per-request data (a theme color from a cookie, a user-preferred width) and a static export isn't feasible. Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes. Choose this fix when the viewport genuinely requires per-request data (a theme color from a cookie, a user-preferred width) and a static export isn't feasible. Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` exempts the segment from instant-navigation validation. The page renders on every request and the navigation blocks until that render completes.
Unlike page body content, viewport metadata can't be deferred behind [`<Suspense>`](https://react.dev/reference/react/Suspense) because it affects the initial HTML `<head>`. Making the viewport dynamic means the entire page navigation blocks. Unlike page body content, viewport metadata can't be deferred behind [`<Suspense>`](https://react.dev/reference/react/Suspense) because it affects the initial HTML `<head>`. Making the viewport dynamic means the entire page navigation blocks.
...@@ -78,12 +78,12 @@ Unlike page body content, viewport metadata can't be deferred behind [`<Suspense ...@@ -78,12 +78,12 @@ Unlike page body content, viewport metadata can't be deferred behind [`<Suspense
#### Opt the layout out #### Opt the layout out
Set [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout that defines `generateViewport`. The layout and every route in its subtree are exempted from instant-navigation validation. Apply this to the nested layout that owns the dynamic viewport, not the root layout, so the opt-out is scoped to the affected subtree. Set [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the layout that defines `generateViewport`. This allows that layout segment to block while descendant segments remain independently validated. Apply this to the nested layout that owns the dynamic viewport, not the root layout, so the opt-out is scoped to the affected segment.
```jsx filename="app/dashboard/layout.js" ```jsx filename="app/dashboard/layout.js"
import { cookies } from 'next/headers' import { cookies } from 'next/headers'
export const unstable_instant = false export const instant = false
export async function generateViewport() { export async function generateViewport() {
const cookieJar = await cookies() const cookieJar = await cookies()
...@@ -112,18 +112,18 @@ Navigations to this route are not instant. The user waits for the full server re ...@@ -112,18 +112,18 @@ Navigations to this route are not instant. The user waits for the full server re
### Gotchas ### Gotchas
- Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Don't want this validation?](#dont-want-this-validation) for the subtree-wide opt-out. - Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. See [Don't want this validation?](#dont-want-this-validation) for the subtree-wide opt-out.
- This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error. - This export does not disable [prerendering](/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error.
- If the dynamic viewport is the only reason the route blocks, consider whether a static default covers most users. A static `themeColor` with a client-side correction after hydration may give a better experience than blocking the entire navigation. - If the dynamic viewport is the only reason the route blocks, consider whether a static default covers most users. A static `themeColor` with a client-side correction after hydration may give a better experience than blocking the entire navigation.
- Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateViewport` and must be statically prerendered. [`unstable_instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) silences the validation error but does not let those routes through, so the build still fails when they prerender. If your root layout's `generateViewport` depends on request data, [Use static viewport](#use-static-viewport) instead, or move to [`global-not-found.js`](/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateViewport`. - Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateViewport` and must be statically prerendered. [`instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) silences the validation error but does not let those routes through, so the build still fails when they prerender. If your root layout's `generateViewport` depends on request data, [Use static viewport](#use-static-viewport) instead, or move to [`global-not-found.js`](/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateViewport`.
## Don't want this validation? ## Don't want this validation?
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -24,7 +24,7 @@ This typically happens when a layout conditionally omits `{children}`, a paralle ...@@ -24,7 +24,7 @@ This typically happens when a layout conditionally omits `{children}`, a paralle
<FixOption <FixOption
group="ignore" group="ignore"
href="#skip-validation-on-the-segment" href="#skip-validation-on-the-segment"
prompt={`Add "export const unstable_instant = false" as a top-level export in the dropped segment's page or layout file. This silences the warning for the dropped segment and tells Next.js the segment does not need instant-navigation validation. Confirm with the user that skipping validation is intentional before applying this change.`} prompt={`Add "export const instant = false" as a top-level export in the dropped segment's page or layout file. This silences the warning for the dropped segment and tells Next.js the segment does not need instant-navigation validation. Confirm with the user that skipping validation is intentional before applying this change.`}
title="Skip validation on the segment" title="Skip validation on the segment"
> >
Opt the dropped segment out of instant-navigation validation. Opt the dropped segment out of instant-navigation validation.
...@@ -107,7 +107,7 @@ The segment is always in the render tree, which means Next.js validates it on ev ...@@ -107,7 +107,7 @@ The segment is always in the render tree, which means Next.js validates it on ev
## Skip validation on the segment ## Skip validation on the segment
Choose this fix when the segment is intentionally not rendered in certain states (a modal that only appears on interaction, a slot gated by authentication). Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the dropped segment tells Next.js to skip validation for it. Choose this fix when the segment is intentionally not rendered in certain states (a modal that only appears on interaction, a slot gated by authentication). Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the dropped segment tells Next.js to skip validation for it.
### Patterns ### Patterns
...@@ -116,7 +116,7 @@ Choose this fix when the segment is intentionally not rendered in certain states ...@@ -116,7 +116,7 @@ Choose this fix when the segment is intentionally not rendered in certain states
Add the export to the page or layout file of the segment that was dropped from rendering. Add the export to the page or layout file of the segment that was dropped from rendering.
```jsx filename="app/dashboard/@modal/page.js" ```jsx filename="app/dashboard/@modal/page.js"
export const unstable_instant = false export const instant = false
export default function ModalPage() { export default function ModalPage() {
return <Modal /> return <Modal />
...@@ -132,15 +132,15 @@ The segment is exempt from instant-navigation validation. If it has issues that ...@@ -132,15 +132,15 @@ The segment is exempt from instant-navigation validation. If it has issues that
### Gotchas ### Gotchas
- The export must be on the **dropped segment's own file** (page or layout), not on a parent. The framework walks top-down and the first explicit config wins. - The export must be on the **dropped segment's own file** (page or layout), not on a parent. The framework walks top-down and the first explicit config wins.
- Setting [`unstable_instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` does not disable [prerendering](/docs/app/glossary#prerendering). The segment still prerenders if it can. It only silences the validation error. - Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` does not disable [prerendering](/docs/app/glossary#prerendering). The segment still prerenders if it can. It only silences the validation error.
## Don't want this validation? ## Don't want this validation?
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. 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. This opts out the segment itself. Child segments are still validated during client navigations. - **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Layout and its children**: add `export const unstable_instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it. - **Layout and its children**: add `export const instant = { unstable_disableValidation: true }` to a layout. This disables validation for that layout and every segment below it.
- **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`. This limits validation to segments that explicitly export `unstable_instant`. - **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`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model.
......
...@@ -4,20 +4,20 @@ title: Invalid Instant Configuration ...@@ -4,20 +4,20 @@ title: Invalid Instant Configuration
## Why This Message Occurred ## Why This Message Occurred
You provided an invalid configuration for `export const unstable_instant` in a Layout or Page file. You provided an invalid configuration for `export const instant` in a Layout or Page file.
### Example of Correct Usage ### Example of Correct Usage
#### Indicating instant UI #### Indicating instant UI
```tsx filename="app/[slug]/page.tsx" ```tsx filename="app/[slug]/page.tsx"
export const unstable_instant = true export const instant = true
``` ```
#### Customizing the validation level #### Customizing the validation level
```tsx filename="app/[slug]/page.tsx" ```tsx filename="app/[slug]/page.tsx"
export const unstable_instant = { export const instant = {
level: 'warning', level: 'warning',
} }
``` ```
...@@ -27,5 +27,5 @@ export const unstable_instant = { ...@@ -27,5 +27,5 @@ export const unstable_instant = {
This does not disable prefetching. This does not disable prefetching.
```tsx filename="app/[slug]/page.tsx" ```tsx filename="app/[slug]/page.tsx"
export const unstable_instant = false export const instant = false
``` ```
...@@ -60,7 +60,7 @@ If you expect this segment to sometimes not render (for example, a modal slot th ...@@ -60,7 +60,7 @@ If you expect this segment to sometimes not render (for example, a modal slot th
```tsx ```tsx
// app/dashboard/@modal/page.tsx // app/dashboard/@modal/page.tsx
export const unstable_instant = false export const instant = false
export default function ModalPage() { export default function ModalPage() {
// ... // ...
......
...@@ -32,7 +32,7 @@ cp -r evals/evals/agent-034-async-cookies evals/evals/agent-042-your-thing ...@@ -32,7 +32,7 @@ cp -r evals/evals/agent-034-async-cookies evals/evals/agent-042-your-thing
Then edit three files: Then edit three files:
**`PROMPT.md`** — what you'd type into the agent. Write it like a real user would: describe the symptom or goal, not the API. "Navigating from `/a` to `/b` is slow, fix it" is a good prompt. "Use `unstable_instant`" is not — you're testing whether the agent understands the feature well enough to reach for it, not whether it can pattern-match a name you handed it. **`PROMPT.md`** — what you'd type into the agent. Write it like a real user would: describe the symptom or goal, not the API. "Navigating from `/a` to `/b` is slow, fix it" is a good prompt. "Use `instant`" is not — you're testing whether the agent understands the feature well enough to reach for it, not whether it can pattern-match a name you handed it.
**`EVAL.ts`** — vitest assertions against files the agent wrote. Regex the source, don't run it. **`EVAL.ts`** — vitest assertions against files the agent wrote. Regex the source, don't run it.
...@@ -43,8 +43,8 @@ import { join } from 'path' ...@@ -43,8 +43,8 @@ import { join } from 'path'
const page = readFileSync(join(process.cwd(), 'app/page.tsx'), 'utf-8') const page = readFileSync(join(process.cwd(), 'app/page.tsx'), 'utf-8')
test('exports unstable_instant', () => { test('exports instant', () => {
expect(page).toMatch(/export const unstable_instant\b/) expect(page).toMatch(/export const instant\b/)
}) })
``` ```
......
...@@ -5,7 +5,7 @@ ...@@ -5,7 +5,7 @@
* *
* The eval harness runs `next build` as a script — with `cacheComponents: true`, * The eval harness runs `next build` as a script — with `cacheComponents: true`,
* the build validates that the caching structure produces an instant static shell. * the build validates that the caching structure produces an instant static shell.
* This test checks the agent actually exported `unstable_instant` (the build would * This test checks the agent actually exported `instant` (the build would
* pass without it, since Suspense alone satisfies the build on a static route). * pass without it, since Suspense alone satisfies the build on a static route).
*/ */
...@@ -56,14 +56,12 @@ function readSourceFiles(dir: string): SourceFile[] { ...@@ -56,14 +56,12 @@ function readSourceFiles(dir: string): SourceFile[] {
const sourceFiles = readSourceFiles(process.cwd()) const sourceFiles = readSourceFiles(process.cwd())
test('unstable_instant exported from the product route', () => { test('instant exported from the product route', () => {
const productPage = sourceFiles.find( const productPage = sourceFiles.find(
(f) => f.path.includes('product') && /page\.(tsx?|jsx?)$/.test(f.path) (f) => f.path.includes('product') && /page\.(tsx?|jsx?)$/.test(f.path)
) )
expect(productPage).toBeDefined() expect(productPage).toBeDefined()
expect(productPage!.content).toMatch( expect(productPage!.content).toMatch(/export\s+(const|var|let)\s+instant\b/)
/export\s+(const|var|let)\s+unstable_instant\b/
)
expect(productPage!.content).toMatch(/prefetch\s*:\s*['"]static['"]/) expect(productPage!.content).toMatch(/prefetch\s*:\s*['"]static['"]/)
}) })
...@@ -360,7 +360,7 @@ export const instantRuntimeDataErrors: ReadyRuntimeError[] = [ ...@@ -360,7 +360,7 @@ export const instantRuntimeDataErrors: ReadyRuntimeError[] = [
runtime: true, runtime: true,
error: Object.assign( error: Object.assign(
new Error( new Error(
'Route "/01-cookies-body": Next.js encountered runtime data during prerendering.\n\n`cookies()`, `headers()`, `params`, or `searchParams` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\n\nWays to fix this:\n - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access\n - [cache] If the runtime data is `params` and they\'re known, prerender them with `generateStaticParams`\n - [block] Set `export const unstable_instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-route' 'Route "/01-cookies-body": Next.js encountered runtime data during prerendering.\n\n`cookies()`, `headers()`, `params`, or `searchParams` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\n\nWays to fix this:\n - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access\n - [cache] If the runtime data is `params` and they\'re known, prerender them with `generateStaticParams`\n - [block] Set `export const instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-route'
), ),
{ __NEXT_ERROR_CODE: 'E1221' } { __NEXT_ERROR_CODE: 'E1221' }
), ),
...@@ -388,7 +388,7 @@ export const instantUncachedDataErrors: ReadyRuntimeError[] = [ ...@@ -388,7 +388,7 @@ export const instantUncachedDataErrors: ReadyRuntimeError[] = [
runtime: true, runtime: true,
error: Object.assign( error: Object.assign(
new Error( new Error(
'Route "/06-uncached-fetch-body": Next.js encountered uncached data during prerendering.\n\n`fetch(...)` or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\n\nWays to fix this:\n - [cache] Cache the data access with `"use cache"`\n - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access\n - [block] Set `export const unstable_instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-route' 'Route "/06-uncached-fetch-body": Next.js encountered uncached data during prerendering.\n\n`fetch(...)` or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered, blocking the page load and leading to a slower user experience.\n\nWays to fix this:\n - [cache] Cache the data access with `"use cache"`\n - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access\n - [block] Set `export const instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-route'
), ),
{ __NEXT_ERROR_CODE: 'E1220' } { __NEXT_ERROR_CODE: 'E1220' }
), ),
...@@ -416,7 +416,7 @@ export const instantViewportErrors: ReadyRuntimeError[] = [ ...@@ -416,7 +416,7 @@ export const instantViewportErrors: ReadyRuntimeError[] = [
runtime: true, runtime: true,
error: Object.assign( error: Object.assign(
new Error( new Error(
'Route "/14-cookies-in-viewport": Next.js encountered runtime data in `generateViewport()`.\n\n`cookies()`, `headers()`, `params`, or `searchParams` in `generateViewport()` prevents the page from being prerendered, leading to a slower user experience.\n\nWays to fix this:\n - [static] Use a static viewport export instead of `generateViewport()`\n - [block] Set `export const unstable_instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-prerender-viewport-runtime' 'Route "/14-cookies-in-viewport": Next.js encountered runtime data in `generateViewport()`.\n\n`cookies()`, `headers()`, `params`, or `searchParams` in `generateViewport()` prevents the page from being prerendered, leading to a slower user experience.\n\nWays to fix this:\n - [static] Use a static viewport export instead of `generateViewport()`\n - [block] Set `export const instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-prerender-viewport-runtime'
), ),
{ __NEXT_ERROR_CODE: 'E1208' } { __NEXT_ERROR_CODE: 'E1208' }
), ),
...@@ -447,7 +447,7 @@ export const instantViewportUncachedErrors: ReadyRuntimeError[] = [ ...@@ -447,7 +447,7 @@ export const instantViewportUncachedErrors: ReadyRuntimeError[] = [
runtime: true, runtime: true,
error: Object.assign( error: Object.assign(
new Error( new Error(
'Route "/15-fetch-in-viewport": Next.js encountered uncached data in `generateViewport()`.\n\n`fetch(...)` or `connection()` in `generateViewport()` prevents the page from being prerendered, leading to a slower user experience.\n\nWays to fix this:\n - [cache] Cache the viewport data with `"use cache"` in `generateViewport()`\n - [block] Set `export const unstable_instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-prerender-viewport-dynamic' 'Route "/15-fetch-in-viewport": Next.js encountered uncached data in `generateViewport()`.\n\n`fetch(...)` or `connection()` in `generateViewport()` prevents the page from being prerendered, leading to a slower user experience.\n\nWays to fix this:\n - [cache] Cache the viewport data with `"use cache"` in `generateViewport()`\n - [block] Set `export const instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-prerender-viewport-dynamic'
), ),
{ __NEXT_ERROR_CODE: 'E1210' } { __NEXT_ERROR_CODE: 'E1210' }
), ),
...@@ -655,7 +655,7 @@ export const instantUnrenderedSegmentErrors: ReadyRuntimeError[] = [ ...@@ -655,7 +655,7 @@ export const instantUnrenderedSegmentErrors: ReadyRuntimeError[] = [
runtime: true, runtime: true,
error: Object.assign( error: Object.assign(
new Error( new Error(
'Route "/81-instant-wrapper-unrendered-segment/trigger": Could not validate that a segment in your UI has instant navigation.\n\nThis segment was dropped from rendering. Issues that would prevent instant navigation will go undetected.\n\nDropped segment:\n test-app/app/81-instant-wrapper-unrendered-segment/trigger/page.tsx\n\nWays to fix this:\n - [render] Render the dropped segment\n - [ignore] Set `export const unstable_instant = false` on the dropped segment to skip validation\n\nLearn more: https://nextjs.org/docs/messages/instant-unrendered-segment' 'Route "/81-instant-wrapper-unrendered-segment/trigger": Could not validate that a segment in your UI has instant navigation.\n\nThis segment was dropped from rendering. Issues that would prevent instant navigation will go undetected.\n\nDropped segment:\n test-app/app/81-instant-wrapper-unrendered-segment/trigger/page.tsx\n\nWays to fix this:\n - [render] Render the dropped segment\n - [ignore] Set `export const instant = false` on the dropped segment to skip validation\n\nLearn more: https://nextjs.org/docs/messages/instant-unrendered-segment'
), ),
{ __NEXT_ERROR_CODE: 'E1286' } { __NEXT_ERROR_CODE: 'E1286' }
), ),
...@@ -672,7 +672,7 @@ export const mixedIssueAndInsightErrors: ReadyRuntimeError[] = [ ...@@ -672,7 +672,7 @@ export const mixedIssueAndInsightErrors: ReadyRuntimeError[] = [
runtime: true, runtime: true,
error: Object.assign( error: Object.assign(
new Error( new Error(
'Route "/nav-cookies-under-suspense": Next.js encountered runtime data during prerendering or a navigation.\n\n`cookies()`, `headers()`, `params`, or `searchParams` accessed outside of `<Suspense>` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\n\nWays to fix this:\n - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access\n - [cache] If the runtime data is `params` and they\'re known, prerender them with `generateStaticParams`\n - [block] Set `export const unstable_instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-route' 'Route "/nav-cookies-under-suspense": Next.js encountered runtime data during prerendering or a navigation.\n\n`cookies()`, `headers()`, `params`, or `searchParams` accessed outside of `<Suspense>` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\n\nWays to fix this:\n - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access\n - [cache] If the runtime data is `params` and they\'re known, prerender them with `generateStaticParams`\n - [block] Set `export const instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-route'
), ),
{ __NEXT_ERROR_CODE: 'E1247' } { __NEXT_ERROR_CODE: 'E1247' }
), ),
...@@ -697,7 +697,7 @@ export const mixedIssueAndInsightErrors: ReadyRuntimeError[] = [ ...@@ -697,7 +697,7 @@ export const mixedIssueAndInsightErrors: ReadyRuntimeError[] = [
runtime: true, runtime: true,
error: Object.assign( error: Object.assign(
new Error( new Error(
'Route "/nav-fetch-under-suspense": Next.js encountered uncached data during prerendering or a navigation.\n\n`fetch(...)` or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\n\nWays to fix this:\n - [cache] Cache the data access with `"use cache"`\n - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access\n - [block] Set `export const unstable_instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-route' 'Route "/nav-fetch-under-suspense": Next.js encountered uncached data during prerendering or a navigation.\n\n`fetch(...)` or `connection()` accessed outside of `<Suspense>` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\n\nWays to fix this:\n - [cache] Cache the data access with `"use cache"`\n - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access\n - [block] Set `export const instant = false` to silence this warning and allow a blocking route\n\nLearn more: https://nextjs.org/docs/messages/blocking-route'
), ),
{ __NEXT_ERROR_CODE: 'E1246' } { __NEXT_ERROR_CODE: 'E1246' }
), ),
......
This diff is collapsed.
...@@ -699,16 +699,16 @@ export async function getAppPageStaticInfo({ ...@@ -699,16 +699,16 @@ export async function getAppPageStaticInfo({
) )
} }
// Prevent use client and unstable_instant in the same file. // Prevent use client and instant in the same file.
if (directives?.has('client') && 'unstable_instant' in config) { if (directives?.has('client') && 'instant' in config) {
throw new Error( throw new Error(
`"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 from "${pageFilePath}" 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 from "${pageFilePath}" to use this API.`
) )
} }
if ('unstable_instant' in config && !nextConfig.cacheComponents) { if ('instant' in config && !nextConfig.cacheComponents) {
throw new Error( throw new Error(
`Route "${page}" cannot use \`export const unstable_instant = ...\` without enabling \`cacheComponents\`.` `Route "${page}" cannot use \`export const instant = ...\` without enabling \`cacheComponents\`.`
) )
} }
...@@ -735,10 +735,10 @@ export async function getAppPageStaticInfo({ ...@@ -735,10 +735,10 @@ export async function getAppPageStaticInfo({
} }
} }
// Prevent combining unstable_dynamicStaleTime and unstable_instant. // Prevent combining unstable_dynamicStaleTime and instant.
if ('unstable_dynamicStaleTime' in config && 'unstable_instant' in config) { if ('unstable_dynamicStaleTime' in config && 'instant' in config) {
throw new Error( throw new Error(
`Page "${page}" cannot use both \`export const unstable_dynamicStaleTime\` and \`export const unstable_instant\`.` `Page "${page}" cannot use both \`export const unstable_dynamicStaleTime\` and \`export const instant\`.`
) )
} }
......
...@@ -136,7 +136,7 @@ const AppSegmentConfigSchema = z.object({ ...@@ -136,7 +136,7 @@ const AppSegmentConfigSchema = z.object({
/** /**
* How this segment should be prefetched. * How this segment should be prefetched.
*/ */
unstable_instant: InstantConfigSchema.optional(), instant: InstantConfigSchema.optional(),
/** /**
* Controls prefetching for this segment. * Controls prefetching for this segment.
...@@ -196,10 +196,10 @@ export function parseAppSegmentConfig( ...@@ -196,10 +196,10 @@ export function parseAppSegmentConfig(
)} on "${route}", must be a non-negative number or false`, )} on "${route}", must be a non-negative number or false`,
} }
} }
case 'unstable_instant': { case 'instant': {
return { return {
// @TODO replace this link with a link to the docs when they are written // @TODO replace this link with a link to the docs when they are written
message: `Invalid unstable_instant value ${JSON.stringify(ctx.data)} on "${route}", must be \`true\`, \`false\`, or an object. Read more at https://nextjs.org/docs/messages/invalid-instant-configuration`, message: `Invalid instant value ${JSON.stringify(ctx.data)} on "${route}", must be \`true\`, \`false\`, or an object. Read more at https://nextjs.org/docs/messages/invalid-instant-configuration`,
} }
} }
case 'prefetch': { case 'prefetch': {
...@@ -264,7 +264,7 @@ export type AppSegmentConfig = { ...@@ -264,7 +264,7 @@ export type AppSegmentConfig = {
/** /**
* How this segment should be prefetched. * How this segment should be prefetched.
*/ */
unstable_instant?: Instant instant?: Instant
/** /**
* Controls prefetching for this segment. * Controls prefetching for this segment.
......
...@@ -71,7 +71,7 @@ checkFields<Diff<{ ...@@ -71,7 +71,7 @@ checkFields<Diff<{
} }
config?: {} config?: {}
generateStaticParams?: Function generateStaticParams?: Function
unstable_instant?: InstantConfigForTypeCheckInternal instant?: InstantConfigForTypeCheckInternal
prefetch?: Prefetch prefetch?: Prefetch
unstable_dynamicStaleTime?: number unstable_dynamicStaleTime?: number
revalidate?: RevalidateRange<TEntry> | false revalidate?: RevalidateRange<TEntry> | false
......
...@@ -149,7 +149,7 @@ const clientHookBlockCard: FixCard = { ...@@ -149,7 +149,7 @@ const clientHookBlockCard: FixCard = {
{ text: 'export const instant = false', highlight: true }, { text: 'export const instant = false', highlight: true },
], ],
prompt: prompt:
'Add "export const unstable_instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally request-time before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request, so navigations to it block until the render completes.', 'Add "export const instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally request-time before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request, so navigations to it block until the render completes.',
} }
const clientHookGspCard: FixCard = { const clientHookGspCard: FixCard = {
...@@ -280,7 +280,7 @@ const unrenderedSegmentCards: FixCard[] = [ ...@@ -280,7 +280,7 @@ const unrenderedSegmentCards: FixCard[] = [
{ text: 'export const instant = false', highlight: true }, { text: 'export const instant = false', highlight: true },
], ],
prompt: prompt:
'Add "export const unstable_instant = false" as a top-level export in the dropped segment\'s page or layout file. This silences the warning for the dropped segment and tells Next.js the segment does not need instant-navigation validation. Confirm with the user that skipping validation is intentional before applying this change.', 'Add "export const instant = false" as a top-level export in the dropped segment\'s page or layout file. This silences the warning for the dropped segment and tells Next.js the segment does not need instant-navigation validation. Confirm with the user that skipping validation is intentional before applying this change.',
}, },
] ]
...@@ -368,7 +368,7 @@ const viewportRuntimeCards: FixCard[] = [ ...@@ -368,7 +368,7 @@ const viewportRuntimeCards: FixCard[] = [
{ text: 'export const instant = false', highlight: true }, { text: 'export const instant = false', highlight: true },
], ],
prompt: prompt:
'Add "export const unstable_instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally fully dynamic before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request.', 'Add "export const instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally fully dynamic before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request.',
}, },
] ]
...@@ -396,7 +396,7 @@ const viewportDynamicCards: FixCard[] = [ ...@@ -396,7 +396,7 @@ const viewportDynamicCards: FixCard[] = [
{ text: 'export const instant = false', highlight: true }, { text: 'export const instant = false', highlight: true },
], ],
prompt: prompt:
'Add "export const unstable_instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally fully dynamic before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request.', 'Add "export const instant = false" as a top-level export in the page or layout file. This silences the warning for this segment. Confirm with the user that the route is intentionally fully dynamic before applying this change: the export exempts the segment from instant-navigation validation, and the route renders on every request.',
}, },
] ]
......
...@@ -459,7 +459,7 @@ describe('getUnrenderedSegmentErrorDetails', () => { ...@@ -459,7 +459,7 @@ describe('getUnrenderedSegmentErrorDetails', () => {
`\n\n${label}:\n${files.map((p) => ` ${p}`).join('\n')}` + `\n\n${label}:\n${files.map((p) => ` ${p}`).join('\n')}` +
`\n\nWays to fix this:` + `\n\nWays to fix this:` +
`\n - [render] Render the dropped segment` + `\n - [render] Render the dropped segment` +
`\n - [ignore] Set \`export const unstable_instant = false\` on the dropped segment to skip validation` + `\n - [ignore] Set \`export const instant = false\` on the dropped segment to skip validation` +
`\n\nLearn more: https://nextjs.org/docs/messages/instant-unrendered-segment` `\n\nLearn more: https://nextjs.org/docs/messages/instant-unrendered-segment`
} }
return new Error(message) return new Error(message)
......
...@@ -363,7 +363,7 @@ export function isSyncIOClientError(message: string): boolean { ...@@ -363,7 +363,7 @@ export function isSyncIOClientError(message: string): boolean {
export function isBlockingRouteInNavError(message: string): boolean { export function isBlockingRouteInNavError(message: string): boolean {
return ( return (
message.includes('or a navigation') || message.includes('or a navigation') ||
message.includes('Could not validate `unstable_instant`') || message.includes('Could not validate `instant`') ||
message.includes( message.includes(
'Could not validate that a segment in your UI has instant navigation' 'Could not validate that a segment in your UI has instant navigation'
) )
......
...@@ -970,7 +970,7 @@ async function generateStagedDynamicFlightRenderResultNode( ...@@ -970,7 +970,7 @@ async function generateStagedDynamicFlightRenderResultNode(
const staticStageByteLengthDeferred = createPromiseWithResolvers<number>() const staticStageByteLengthDeferred = createPromiseWithResolvers<number>()
// Check if this route has opted into runtime prefetching via // Check if this route has opted into runtime prefetching via
// unstable_instant. If so, we piggyback on the dynamic render to fill caches // instant. If so, we piggyback on the dynamic render to fill caches
// and then spawn a final runtime prerender whose result stream is embedded in // and then spawn a final runtime prerender whose result stream is embedded in
// the RSC payload. This is gated on the explicit opt-in because it adds extra // the RSC payload. This is gated on the explicit opt-in because it adds extra
// server processing, increases the response payload size, and the runtime // server processing, increases the response payload size, and the runtime
...@@ -5798,7 +5798,7 @@ async function validateStagedShell( ...@@ -5798,7 +5798,7 @@ async function validateStagedShell(
* shallowest. At each depth, builds a combined payload where segments * shallowest. At each depth, builds a combined payload where segments
* above the boundary use Dynamic stage (already mounted) and segments * above the boundary use Dynamic stage (already mounted) and segments
* below use Static/Runtime stage (being prefetched). If the new subtree * below use Static/Runtime stage (being prefetched). If the new subtree
* contains any `unstable_instant` configs, the payload is rendered to * contains any `instant` configs, the payload is rendered to
* detect dynamic holes without Suspense. * detect dynamic holes without Suspense.
*/ */
async function validateInstantConfigs( async function validateInstantConfigs(
...@@ -6511,7 +6511,7 @@ async function validateInstantConfigsInBuild( ...@@ -6511,7 +6511,7 @@ async function validateInstantConfigsInBuild(
} }
/** /**
* Runs instant validation at build time using the `samples` from `unstable_instant`. * Runs instant validation at build time using the `samples` from `instant`.
* *
* For each sample, this creates a staged RSC render with a synthetic `RequestStore` * For each sample, this creates a staged RSC render with a synthetic `RequestStore`
* populated from sample data, then feeds the accumulated chunks to * populated from sample data, then feeds the accumulated chunks to
......
...@@ -7,7 +7,7 @@ export function createRuntimeBodyError(route: string): Error { ...@@ -7,7 +7,7 @@ export function createRuntimeBodyError(route: string): Error {
` https://nextjs.org/docs/messages/blocking-prerender-runtime#wrap-in-or-move-into-suspense\n` + ` https://nextjs.org/docs/messages/blocking-prerender-runtime#wrap-in-or-move-into-suspense\n` +
` - [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\`\n` + ` - [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\`\n` +
` https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender\n` + ` https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender\n` +
` - [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route\n` + ` - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route\n` +
` https://nextjs.org/docs/messages/blocking-prerender-runtime#allow-blocking-route` ` https://nextjs.org/docs/messages/blocking-prerender-runtime#allow-blocking-route`
) )
} }
...@@ -21,7 +21,7 @@ export function createDynamicBodyError(route: string): Error { ...@@ -21,7 +21,7 @@ export function createDynamicBodyError(route: string): Error {
` https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense\n` + ` https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense\n` +
` - [cache] Cache the data access with \`"use cache"\`\n` + ` - [cache] Cache the data access with \`"use cache"\`\n` +
` https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data\n` + ` https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data\n` +
` - [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route\n` + ` - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route\n` +
` https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route` ` https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route`
) )
} }
...@@ -35,7 +35,7 @@ export function createRuntimeBodyErrorInNavigation(route: string): Error { ...@@ -35,7 +35,7 @@ export function createRuntimeBodyErrorInNavigation(route: string): Error {
` https://nextjs.org/docs/messages/blocking-prerender-runtime#wrap-in-or-move-into-suspense\n` + ` https://nextjs.org/docs/messages/blocking-prerender-runtime#wrap-in-or-move-into-suspense\n` +
` - [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\`\n` + ` - [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\`\n` +
` https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender\n` + ` https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender\n` +
` - [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route\n` + ` - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route\n` +
` https://nextjs.org/docs/messages/blocking-prerender-runtime#allow-blocking-route` ` https://nextjs.org/docs/messages/blocking-prerender-runtime#allow-blocking-route`
) )
} }
...@@ -49,7 +49,7 @@ export function createDynamicBodyErrorInNavigation(route: string): Error { ...@@ -49,7 +49,7 @@ export function createDynamicBodyErrorInNavigation(route: string): Error {
` https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense\n` + ` https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense\n` +
` - [cache] Cache the data access with \`"use cache"\`\n` + ` - [cache] Cache the data access with \`"use cache"\`\n` +
` https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data\n` + ` https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data\n` +
` - [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route\n` + ` - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route\n` +
` https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route` ` https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route`
) )
} }
...@@ -70,7 +70,7 @@ export function createDynamicOrRuntimeBodyError(route: string): Error { ...@@ -70,7 +70,7 @@ export function createDynamicOrRuntimeBodyError(route: string): Error {
` https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data\n` + ` https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data\n` +
` - [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\`\n` + ` - [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\`\n` +
` https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender\n` + ` https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender\n` +
` - [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route\n` + ` - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route\n` +
` https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route` ` https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route`
) )
} }
...@@ -106,7 +106,7 @@ export function createRuntimeViewportError(route: string): Error { ...@@ -106,7 +106,7 @@ export function createRuntimeViewportError(route: string): Error {
`Ways to fix this:\n` + `Ways to fix this:\n` +
` - [static] Use a static viewport export instead of \`generateViewport()\`\n` + ` - [static] Use a static viewport export instead of \`generateViewport()\`\n` +
` https://nextjs.org/docs/messages/blocking-prerender-viewport-runtime#use-static-viewport\n` + ` https://nextjs.org/docs/messages/blocking-prerender-viewport-runtime#use-static-viewport\n` +
` - [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route\n` + ` - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route\n` +
` https://nextjs.org/docs/messages/blocking-prerender-viewport-runtime#allow-blocking-route` ` https://nextjs.org/docs/messages/blocking-prerender-viewport-runtime#allow-blocking-route`
) )
} }
...@@ -118,7 +118,7 @@ export function createDynamicViewportError(route: string): Error { ...@@ -118,7 +118,7 @@ export function createDynamicViewportError(route: string): Error {
`Ways to fix this:\n` + `Ways to fix this:\n` +
` - [cache] Cache the viewport data with \`"use cache"\` in \`generateViewport()\`\n` + ` - [cache] Cache the viewport data with \`"use cache"\` in \`generateViewport()\`\n` +
` https://nextjs.org/docs/messages/blocking-prerender-viewport-dynamic#cache-the-viewport-data\n` + ` https://nextjs.org/docs/messages/blocking-prerender-viewport-dynamic#cache-the-viewport-data\n` +
` - [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route\n` + ` - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route\n` +
` https://nextjs.org/docs/messages/blocking-prerender-viewport-dynamic#allow-blocking-route` ` https://nextjs.org/docs/messages/blocking-prerender-viewport-dynamic#allow-blocking-route`
) )
} }
...@@ -137,7 +137,7 @@ export function createDynamicOrRuntimeViewportError(route: string): Error { ...@@ -137,7 +137,7 @@ export function createDynamicOrRuntimeViewportError(route: string): Error {
` https://nextjs.org/docs/messages/blocking-prerender-viewport-runtime#use-static-viewport\n` + ` https://nextjs.org/docs/messages/blocking-prerender-viewport-runtime#use-static-viewport\n` +
` - [cache] For uncached data (\`fetch\`, database calls): cache the viewport with \`"use cache"\` in \`generateViewport()\`\n` + ` - [cache] For uncached data (\`fetch\`, database calls): cache the viewport with \`"use cache"\` in \`generateViewport()\`\n` +
` https://nextjs.org/docs/messages/blocking-prerender-viewport-dynamic#cache-the-viewport-data\n` + ` https://nextjs.org/docs/messages/blocking-prerender-viewport-dynamic#cache-the-viewport-data\n` +
` - [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route\n` + ` - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route\n` +
` https://nextjs.org/docs/messages/blocking-prerender-viewport-dynamic#allow-blocking-route` ` https://nextjs.org/docs/messages/blocking-prerender-viewport-dynamic#allow-blocking-route`
) )
} }
......
...@@ -425,7 +425,7 @@ async function collectPrefetchHintsImpl( ...@@ -425,7 +425,7 @@ async function collectPrefetchHintsImpl(
inlinedBytes: number inlinedBytes: number
}> { }> {
// Check if static prefetching is disabled for this segment (runtime // Check if static prefetching is disabled for this segment (runtime
// prefetch or unstable_instant = false). Such segments act as transparent // prefetch or instant = false). Such segments act as transparent
// pass-throughs in the bundle chain: they contribute zero bytes of their // pass-throughs in the bundle chain: they contribute zero bytes of their
// own and pass parent data through to children. However, they cannot be // own and pass parent data through to children. However, they cannot be
// the terminal of a chain — if no child accepts the parent data, the // the terminal of a chain — if no child accepts the parent data, the
......
...@@ -30,14 +30,12 @@ async function createFlightRouterStateFromLoaderTreeImpl( ...@@ -30,14 +30,12 @@ async function createFlightRouterStateFromLoaderTreeImpl(
{}, {},
] ]
// Load the layout or page module to check its unstable_instant and prefetch // Load the layout or page module to check its instant and prefetch
// configs. When a segment doesn't export prefetch, it defaults to // configs. When a segment doesn't export prefetch, it defaults to
// 'partial' if the app has opted into partial prefetching globally via the // 'partial' if the app has opted into partial prefetching globally via the
// `partialPrefetching` config in next.config.js. // `partialPrefetching` config in next.config.js.
const mod = layout ? await layout[0]() : page ? await page[0]() : undefined const mod = layout ? await layout[0]() : page ? await page[0]() : undefined
const instantConfig = mod const instantConfig = mod ? (mod as AppSegmentConfig).instant : undefined
? (mod as AppSegmentConfig).unstable_instant
: undefined
const prefetchConfig = const prefetchConfig =
(mod ? (mod as AppSegmentConfig).prefetch : undefined) ?? (mod ? (mod as AppSegmentConfig).prefetch : undefined) ??
(partialPrefetching === 'unstable_eager' (partialPrefetching === 'unstable_eager'
...@@ -120,7 +118,7 @@ async function createFlightRouterStateFromLoaderTreeImpl( ...@@ -120,7 +118,7 @@ async function createFlightRouterStateFromLoaderTreeImpl(
} }
// Mark the segment as "eager" unless its effective prefetch strategy is // Mark the segment as "eager" unless its effective prefetch strategy is
// 'partial' or 'allow-runtime'. A truthy unstable_instant is treated as // 'partial' or 'allow-runtime'. A truthy instant is treated as
// 'partial' (not eager). 'unstable_eager' already set the bit above. Under // 'partial' (not eager). 'unstable_eager' already set the bit above. Under
// App Shells, a subtree with no eager segment skips its Speculative prefetch // App Shells, a subtree with no eager segment skips its Speculative prefetch
// and relies on the shared app shell instead. // and relies on the shared app shell instead.
......
...@@ -1001,7 +1001,7 @@ export function trackDynamicHoleInNavigation( ...@@ -1001,7 +1001,7 @@ export function trackDynamicHoleInNavigation(
// If shared parents blocked us from validating, we should only log // If shared parents blocked us from validating, we should only log
// the errors from the innermost (segments), i.e. omit layouts whose // the errors from the innermost (segments), i.e. omit layouts whose
// slots managed to render (because clearly they didn't block validation) // slots managed to render (because clearly they didn't block validation)
const message = `Route "${workStore.route}": Could not validate \`unstable_instant\` because a Client Component in a parent segment prevented the page from rendering.` const message = `Route "${workStore.route}": Could not validate \`instant\` because a Client Component in a parent segment prevented the page from rendering.`
const error = addErrorContext( const error = addErrorContext(
new Error(message), new Error(message),
componentStack, componentStack,
...@@ -1117,7 +1117,7 @@ export function trackThrownErrorInNavigation( ...@@ -1117,7 +1117,7 @@ export function trackThrownErrorInNavigation(
// invalid - fallthrough // invalid - fallthrough
} }
} }
const message = `Route "${workStore.route}": Could not validate \`unstable_instant\` because an error prevented the target segment from rendering.` const message = `Route "${workStore.route}": Could not validate \`instant\` because an error prevented the target segment from rendering.`
const error = addErrorContext( const error = addErrorContext(
new Error(message, { cause: thrownValue }), new Error(message, { cause: thrownValue }),
componentStack, componentStack,
...@@ -1335,7 +1335,7 @@ export function throwIfDisallowedDynamic( ...@@ -1335,7 +1335,7 @@ export function throwIfDisallowedDynamic(
} }
// Either flag expresses "this shell is allowed to be empty/blocking": // Either flag expresses "this shell is allowed to be empty/blocking":
// - `allowEmptyStaticShell` covers `unstable_instant = false` (user opt-in) // - `allowEmptyStaticShell` covers `instant = false` (user opt-in)
// and the build-phase fallback-shell case. // and the build-phase fallback-shell case.
// - `hasSuspenseAboveBody` is the structural opt-in inside the user's root // - `hasSuspenseAboveBody` is the structural opt-in inside the user's root
// layout. // layout.
...@@ -1401,7 +1401,7 @@ export function getStaticShellDisallowedDynamicReasons( ...@@ -1401,7 +1401,7 @@ export function getStaticShellDisallowedDynamicReasons(
} }
// Either flag expresses "this shell is allowed to be empty/blocking": // Either flag expresses "this shell is allowed to be empty/blocking":
// - `allowEmptyStaticShell` covers `unstable_instant = false` (user opt-in) // - `allowEmptyStaticShell` covers `instant = false` (user opt-in)
// and the build-phase fallback-shell case. // and the build-phase fallback-shell case.
// - `hasSuspenseAboveBody` is the structural opt-in inside the user's root // - `hasSuspenseAboveBody` is the structural opt-in inside the user's root
// layout. // layout.
...@@ -1542,7 +1542,7 @@ export function getNavigationDisallowedDynamicReasons( ...@@ -1542,7 +1542,7 @@ export function getNavigationDisallowedDynamicReasons(
`\n\nWays to fix this:` + `\n\nWays to fix this:` +
`\n - [render] Render the dropped segment` + `\n - [render] Render the dropped segment` +
`\n https://nextjs.org/docs/messages/instant-unrendered-segment#render-the-dropped-segment` + `\n https://nextjs.org/docs/messages/instant-unrendered-segment#render-the-dropped-segment` +
`\n - [ignore] Set \`export const unstable_instant = false\` on the dropped segment to skip validation` + `\n - [ignore] Set \`export const instant = false\` on the dropped segment to skip validation` +
`\n https://nextjs.org/docs/messages/instant-unrendered-segment#skip-validation-on-the-segment` `\n https://nextjs.org/docs/messages/instant-unrendered-segment#skip-validation-on-the-segment`
} }
const error = new Error(message) const error = new Error(message)
...@@ -1553,7 +1553,7 @@ export function getNavigationDisallowedDynamicReasons( ...@@ -1553,7 +1553,7 @@ export function getNavigationDisallowedDynamicReasons(
// render. Suppress the validation failure to avoid noise. // render. Suppress the validation failure to avoid noise.
return [] return []
} else if (thrownErrorsOutsideBoundary.length === 1) { } else if (thrownErrorsOutsideBoundary.length === 1) {
const message = `Route "${workStore.route}": Could not validate \`unstable_instant\` because the target segment was prevented from rendering, likely due to the following error.` const message = `Route "${workStore.route}": Could not validate \`instant\` because the target segment was prevented from rendering, likely due to the following error.`
const error = rootInstantStack !== null ? rootInstantStack() : new Error() const error = rootInstantStack !== null ? rootInstantStack() : new Error()
error.name = 'Error' error.name = 'Error'
error.message = message error.message = message
...@@ -1562,7 +1562,7 @@ export function getNavigationDisallowedDynamicReasons( ...@@ -1562,7 +1562,7 @@ export function getNavigationDisallowedDynamicReasons(
thrownErrorsOutsideBoundary[0] as Error, thrownErrorsOutsideBoundary[0] as Error,
]) ])
} else { } else {
const message = `Route "${workStore.route}": Could not validate \`unstable_instant\` because the target segment was prevented from rendering, likely due to one of the following errors.` const message = `Route "${workStore.route}": Could not validate \`instant\` because the target segment was prevented from rendering, likely due to one of the following errors.`
const error = rootInstantStack !== null ? rootInstantStack() : new Error() const error = rootInstantStack !== null ? rootInstantStack() : new Error()
error.name = 'Error' error.name = 'Error'
error.message = message error.message = message
......
...@@ -41,7 +41,7 @@ export function isImplicitValidationSegment(segment: Segment): boolean { ...@@ -41,7 +41,7 @@ export function isImplicitValidationSegment(segment: Segment): boolean {
* a non-manual default validation level. Even when the user provides their * a non-manual default validation level. Even when the user provides their
* own `global-error` or root `not-found`, these pages are special-purpose * own `global-error` or root `not-found`, these pages are special-purpose
* error UI — opting them into validation is something the user can do * error UI — opting them into validation is something the user can do
* explicitly via `unstable_instant`. * explicitly via `instant`.
*/ */
export function isFrameworkErrorRoute(route: string | undefined): boolean { export function isFrameworkErrorRoute(route: string | undefined): boolean {
return ( return (
...@@ -81,7 +81,7 @@ export async function isPageAllowedToBlock(tree: LoaderTree): Promise<boolean> { ...@@ -81,7 +81,7 @@ export async function isPageAllowedToBlock(tree: LoaderTree): Promise<boolean> {
// TODO(restart-on-cache-miss): Does this work correctly for client page/layout modules? // TODO(restart-on-cache-miss): Does this work correctly for client page/layout modules?
const instantConfig = layoutOrPageMod const instantConfig = layoutOrPageMod
? (layoutOrPageMod as AppSegmentConfig).unstable_instant ? (layoutOrPageMod as AppSegmentConfig).instant
: undefined : undefined
// If we encounter a non-false instant config before a instant=false, // If we encounter a non-false instant config before a instant=false,
...@@ -117,7 +117,7 @@ enum VALIDATION_LEVEL { ...@@ -117,7 +117,7 @@ enum VALIDATION_LEVEL {
* Walks the loader tree and checks if any segment has an `instant` config * Walks the loader tree and checks if any segment has an `instant` config
* that needs validating for the given mode. * that needs validating for the given mode.
* *
* - Explicit `unstable_instant` exports are checked against mode. * - Explicit `instant` exports are checked against mode.
* - Page and default segments without an explicit config get implicit * - Page and default segments without an explicit config get implicit
* validation when the default validation level applies to this mode. * validation when the default validation level applies to this mode.
* - `unstable_disableValidation` on any segment kills validation for * - `unstable_disableValidation` on any segment kills validation for
...@@ -170,7 +170,7 @@ async function anySegmentNeedsInstantValidation( ...@@ -170,7 +170,7 @@ async function anySegmentNeedsInstantValidation(
const { mod: layoutOrPageMod } = await getLayoutOrPageModule(tree) const { mod: layoutOrPageMod } = await getLayoutOrPageModule(tree)
const instantConfig = layoutOrPageMod const instantConfig = layoutOrPageMod
? (layoutOrPageMod as AppSegmentConfig).unstable_instant ? (layoutOrPageMod as AppSegmentConfig).instant
: undefined : undefined
if (instantConfig === false) { if (instantConfig === false) {
...@@ -239,7 +239,7 @@ export const resolveInstantConfigSamplesForPage = async ( ...@@ -239,7 +239,7 @@ export const resolveInstantConfigSamplesForPage = async (
const { mod: layoutOrPageMod } = await getLayoutOrPageModule(tree) const { mod: layoutOrPageMod } = await getLayoutOrPageModule(tree)
const instantConfig = layoutOrPageMod const instantConfig = layoutOrPageMod
? (layoutOrPageMod as AppSegmentConfig).unstable_instant ? (layoutOrPageMod as AppSegmentConfig).instant
: undefined : undefined
let samples: InstantSample[] | null = null let samples: InstantSample[] | null = null
......
...@@ -61,7 +61,7 @@ export function expectCompleteParamsInClientValidation( ...@@ -61,7 +61,7 @@ export function expectCompleteParamsInClientValidation(
const missingParams = Array.from(fallbackParams.keys()) const missingParams = Array.from(fallbackParams.keys())
trackMissingSampleErrorAndThrow( trackMissingSampleErrorAndThrow(
new InstantValidationError( new InstantValidationError(
`Route "${workStore.route}" called ${expression} but param${missingParams.length > 1 ? 's' : ''} ${missingParams.map((p) => `"${p}"`).join(', ')} ${missingParams.length > 1 ? 'are' : 'is'} not defined in the \`unstable_samples\` of \`unstable_instant\`. ` + `Route "${workStore.route}" called ${expression} but param${missingParams.length > 1 ? 's' : ''} ${missingParams.map((p) => `"${p}"`).join(', ')} ${missingParams.length > 1 ? 'are' : 'is'} not defined in the \`unstable_samples\` of \`instant\`. ` +
`${expression} requires all route params to be provided.` `${expression} requires all route params to be provided.`
) )
) )
......
...@@ -151,7 +151,7 @@ function createMissingCookieSampleError( ...@@ -151,7 +151,7 @@ function createMissingCookieSampleError(
): InstantValidationError { ): InstantValidationError {
return new InstantValidationError( return new InstantValidationError(
`Route "${route}" accessed cookie "${name}" which is not defined in the \`unstable_samples\` ` + `Route "${route}" accessed cookie "${name}" which is not defined in the \`unstable_samples\` ` +
`of \`unstable_instant\`. Add it to the sample's \`cookies\` array, ` + `of \`instant\`. Add it to the sample's \`cookies\` array, ` +
`or \`{ name: "${name}", value: null }\` if it should be absent.` `or \`{ name: "${name}", value: null }\` if it should be absent.`
) )
} }
...@@ -207,7 +207,7 @@ export function createHeadersFromSample( ...@@ -207,7 +207,7 @@ export function createHeadersFromSample(
trackMissingSampleErrorAndThrow( trackMissingSampleErrorAndThrow(
new InstantValidationError( new InstantValidationError(
`Route "${route}" accessed header "${name}" which is not defined in the \`unstable_samples\` ` + `Route "${route}" accessed header "${name}" which is not defined in the \`unstable_samples\` ` +
`of \`unstable_instant\`. Add it to the sample's \`headers\` array, ` + `of \`instant\`. Add it to the sample's \`headers\` array, ` +
`or \`["${name}", null]\` if it should be absent.` `or \`["${name}", null]\` if it should be absent.`
) )
) )
...@@ -270,7 +270,7 @@ export function createExhaustiveParamsProxy<TParams extends Params>( ...@@ -270,7 +270,7 @@ export function createExhaustiveParamsProxy<TParams extends Params>(
trackMissingSampleErrorAndThrow( trackMissingSampleErrorAndThrow(
new InstantValidationError( new InstantValidationError(
`Route "${route}" accessed param "${prop}" which is not defined in the \`unstable_samples\` ` + `Route "${route}" accessed param "${prop}" which is not defined in the \`unstable_samples\` ` +
`of \`unstable_instant\`. Add it to the sample's \`params\` object.` `of \`instant\`. Add it to the sample's \`params\` object.`
) )
) )
} }
...@@ -360,7 +360,7 @@ function createMissingSearchParamSampleError( ...@@ -360,7 +360,7 @@ function createMissingSearchParamSampleError(
): InstantValidationError { ): InstantValidationError {
return new InstantValidationError( return new InstantValidationError(
`Route "${route}" accessed searchParam "${name}" which is not defined in the \`unstable_samples\` ` + `Route "${route}" accessed searchParam "${name}" which is not defined in the \`unstable_samples\` ` +
`of \`unstable_instant\`. Add it to the sample's \`searchParams\` object, ` + `of \`instant\`. Add it to the sample's \`searchParams\` object, ` +
`or \`{ "${name}": null }\` if it should be absent.` `or \`{ "${name}": null }\` if it should be absent.`
) )
} }
...@@ -489,7 +489,7 @@ export function assertRootParamInSamples( ...@@ -489,7 +489,7 @@ export function assertRootParamInSamples(
trackMissingSampleErrorAndThrow( trackMissingSampleErrorAndThrow(
new InstantValidationError( new InstantValidationError(
`Route "${route}" accessed root param "${paramName}" which is not defined in the \`unstable_samples\` ` + `Route "${route}" accessed root param "${paramName}" which is not defined in the \`unstable_samples\` ` +
`of \`unstable_instant\`. Add it to the sample's \`params\` object.` `of \`instant\`. Add it to the sample's \`params\` object.`
) )
) )
} }
......
...@@ -1190,13 +1190,12 @@ export async function createCombinedPayloadAtDepth( ...@@ -1190,13 +1190,12 @@ export async function createCombinedPayloadAtDepth(
let prefetchConfig: AppSegmentConfig['prefetch'] | null = null let prefetchConfig: AppSegmentConfig['prefetch'] | null = null
let localCreateInstantStack: (() => Error) | null = null let localCreateInstantStack: (() => Error) | null = null
if (layoutOrPageMod !== undefined) { if (layoutOrPageMod !== undefined) {
instantConfig = instantConfig = (layoutOrPageMod as AppSegmentConfig).instant ?? null
(layoutOrPageMod as AppSegmentConfig).unstable_instant ?? null
prefetchConfig = (layoutOrPageMod as AppSegmentConfig).prefetch ?? null prefetchConfig = (layoutOrPageMod as AppSegmentConfig).prefetch ?? null
// When the default validation level is active and this is a page or // When the default validation level is active and this is a page or
// default segment without an explicit config, treat it as if // default segment without an explicit config, treat it as if
// unstable_instant = true was exported. Framework-synthesized error // instant = true was exported. Framework-synthesized error
// routes are excluded — see isFrameworkErrorRoute. // routes are excluded — see isFrameworkErrorRoute.
if ( if (
instantConfig === null && instantConfig === null &&
......
...@@ -227,7 +227,7 @@ export interface RenderOptsPartial { ...@@ -227,7 +227,7 @@ export interface RenderOptsPartial {
/** /**
* When true, attempt to run build-time instant validation for this prerender. * When true, attempt to run build-time instant validation for this prerender.
* Only the first prerender per page sets this, since validation uses * Only the first prerender per page sets this, since validation uses
* unstable_instant.unstable_samples and is independent of actual route params. * instant.unstable_samples and is independent of actual route params.
*/ */
runInstantValidation?: boolean runInstantValidation?: boolean
} }
......
...@@ -1092,9 +1092,9 @@ export interface ExperimentalConfig { ...@@ -1092,9 +1092,9 @@ export interface ExperimentalConfig {
* Controls the validation behavior of Instant Insights * Controls the validation behavior of Instant Insights
* *
* - `'warning'` (default): Validates all navigations for Instant UI in development * - `'warning'` (default): Validates all navigations for Instant UI in development
* - `'manual-warning'`: Validates navigations for Instant UI in development only when configured with `unstable_instant` in Pages and Layouts * - `'manual-warning'`: Validates navigations for Instant UI in development only when configured with `instant` in Pages and Layouts
* - `'experimental-error'`: Validates all navigations for Instant in development and build. Use with caution. * - `'experimental-error'`: Validates all navigations for Instant in development and build. Use with caution.
* - `'experimental-manual-error'`: Validates navigations for Instant UI in development and build when configured with `unstable_instant` in Pages and Layouts. Use with caution. * - `'experimental-manual-error'`: Validates navigations for Instant UI in development and build when configured with `instant` in Pages and Layouts. Use with caution.
*/ */
validationLevel?: ValidationLevel validationLevel?: ValidationLevel
} }
...@@ -1345,7 +1345,7 @@ export type ExportPathMap = { ...@@ -1345,7 +1345,7 @@ export type ExportPathMap = {
/** /**
* When true, run build-time instant validation for this export path. * When true, run build-time instant validation for this export path.
* Only set on the first export entry per page, since validation uses * Only set on the first export entry per page, since validation uses
* unstable_instant.unstable_samples (not actual params from generateStaticParams), * instant.unstable_samples (not actual params from generateStaticParams),
* so the result is the same for all param combinations. * so the result is the same for all param combinations.
* *
* @internal * @internal
......
...@@ -46,7 +46,7 @@ export class ClientHookDynamicError extends Error { ...@@ -46,7 +46,7 @@ export class ClientHookDynamicError extends Error {
`Ways to fix this:\n` + `Ways to fix this:\n` +
` - [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering\n` + ` - [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering\n` +
` https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense\n` + ` https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense\n` +
` - [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route\n` + ` - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route\n` +
` https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route` ` https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route`
) )
} }
...@@ -68,7 +68,7 @@ export class ParamClientHookDynamicError extends Error { ...@@ -68,7 +68,7 @@ export class ParamClientHookDynamicError extends Error {
` - [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering\n` + ` - [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering\n` +
` https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense\n` + ` https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense\n` +
cacheBullet + cacheBullet +
` - [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route\n` + ` - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route\n` +
` https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route` ` https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route`
) )
} }
......
...@@ -146,15 +146,15 @@ const API_DOCS: Record< ...@@ -146,15 +146,15 @@ const API_DOCS: Record<
'`maxDuration` allows you to set max default execution time for your function. If it is not specified, the default value is dependent on your deployment platform and plan.', '`maxDuration` allows you to set max default execution time for your function. If it is not specified, the default value is dependent on your deployment platform and plan.',
link: 'https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#maxduration', link: 'https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#maxduration',
}, },
unstable_instant: { instant: {
description: `Enables instant navigation validation for this segment. This configuration is currently under development and will change.`, description: `Enables instant navigation validation for this segment.`,
link: '(docs coming soon)', link: 'https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant',
type: 'true | object | false', type: 'true | object | false',
// TODO: ideally, we'd validate the config object somehow, but this is difficult to do // TODO: ideally, we'd validate the config object somehow, but this is difficult to do
// with the way this plugin is currently structured. // with the way this plugin is currently structured.
// For now, since we don't provide an `options` here, we won't do any validation in // For now, since we don't provide an `options` here, we won't do any validation in
// `getSemanticDiagnosticsForExportVariableStatement` below, and only provide hover a tooltip + autocomplete. // `getSemanticDiagnosticsForExportVariableStatement` below, and only provide hover a tooltip + autocomplete.
insertText: 'unstable_instant = true;', insertText: 'instant = true;',
}, },
prefetch: { prefetch: {
description: `Controls prefetching behavior for this segment. Some options are experimental and may change.`, description: `Controls prefetching behavior for this segment. Some options are experimental and may change.`,
...@@ -175,7 +175,7 @@ const API_DOCS: Record< ...@@ -175,7 +175,7 @@ const API_DOCS: Record<
insertText: `prefetch = 'allow-runtime';`, insertText: `prefetch = 'allow-runtime';`,
}, },
unstable_dynamicStaleTime: { unstable_dynamicStaleTime: {
description: `Controls how long the client-side router cache retains dynamic page data (in seconds). Pages only — not allowed in layouts. Cannot be combined with \`unstable_instant\`.`, description: `Controls how long the client-side router cache retains dynamic page data (in seconds). Pages only — not allowed in layouts. Cannot be combined with \`instant\`.`,
link: '(docs coming soon)', link: '(docs coming soon)',
type: 'number', type: 'number',
isValid: (value: string) => { isValid: (value: string) => {
......
...@@ -181,11 +181,11 @@ export type FlightRouterState = [ ...@@ -181,11 +181,11 @@ export type FlightRouterState = [
export type CompressedRefreshState = [url: string, renderedSearch: string] export type CompressedRefreshState = [url: string, renderedSearch: string]
export const enum PrefetchHint { export const enum PrefetchHint {
// This segment has a runtime prefetch enabled (via unstable_instant with // This segment has a runtime prefetch enabled (via instant with
// prefetch: 'runtime'). Per-segment only, does not propagate to ancestors. // prefetch: 'runtime'). Per-segment only, does not propagate to ancestors.
HasRuntimePrefetch = 0b00001, HasRuntimePrefetch = 0b00001,
// This segment or one of its descendants opts into Partial Prefetching. // This segment or one of its descendants opts into Partial Prefetching.
// Currently set when a truthy unstable_instant config is present on any // Currently set when a truthy instant config is present on any
// segment in the subtree (regardless of prefetch mode). Propagates upward // segment in the subtree (regardless of prefetch mode). Propagates upward
// so the root segment reflects the entire subtree. // so the root segment reflects the entire subtree.
SubtreeHasPartialPrefetching = 0b00010, SubtreeHasPartialPrefetching = 0b00010,
...@@ -215,7 +215,7 @@ export const enum PrefetchHint { ...@@ -215,7 +215,7 @@ export const enum PrefetchHint {
// re-fetched with correct hints. Only set during build-time prerendering, // re-fetched with correct hints. Only set during build-time prerendering,
// never at runtime. // never at runtime.
InliningHintsStale = 0b1000000000, InliningHintsStale = 0b1000000000,
// This segment has unstable_instant = false, opting out of all // This segment has instant = false, opting out of all
// prefetching entirely (neither static nor runtime). // prefetching entirely (neither static nor runtime).
PrefetchDisabled = 0b10000000000, PrefetchDisabled = 0b10000000000,
// This segment or one of its descendants has runtime prefetch enabled // This segment or one of its descendants has runtime prefetch enabled
...@@ -234,7 +234,7 @@ export const enum PrefetchHint { ...@@ -234,7 +234,7 @@ export const enum PrefetchHint {
* Bitmask for checking whether a segment's static prefetch is skipped. Matches * Bitmask for checking whether a segment's static prefetch is skipped. Matches
* if EITHER bit is set — i.e. the segment uses runtime prefetching * if EITHER bit is set — i.e. the segment uses runtime prefetching
* (HasRuntimePrefetch) OR prefetching is disabled entirely (PrefetchDisabled, * (HasRuntimePrefetch) OR prefetching is disabled entirely (PrefetchDisabled,
* e.g. unstable_instant = false). The segment participates in the bundle chain * e.g. instant = false). The segment participates in the bundle chain
* but with null data. * but with null data.
* *
* Usage: `(hints & StaticPrefetchDisabled) !== 0` * Usage: `(hints & StaticPrefetchDisabled) !== 0`
......
...@@ -84,6 +84,6 @@ prefetch = 'allow-runtime' route-level: permits runtime ...@@ -84,6 +84,6 @@ prefetch = 'allow-runtime' route-level: permits runtime
prefetching of private-cached prefetching of private-cached
content when <Link> is visible content when <Link> is visible
unstable_instant = false layout-level opt-out; escape instant = false layout-level opt-out; escape
hatch, anti-pattern hatch, anti-pattern
``` ```
...@@ -3,7 +3,7 @@ import { CachedData } from '../../data-fetching' ...@@ -3,7 +3,7 @@ import { CachedData } from '../../data-fetching'
import { connection } from 'next/server' import { connection } from 'next/server'
import { Suspense } from 'react' import { Suspense } from 'react'
export const unstable_instant = true export const instant = true
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
const CACHE_KEY = __dirname + '/__PAGE__' const CACHE_KEY = __dirname + '/__PAGE__'
......
...@@ -2,7 +2,7 @@ import { Suspense } from 'react' ...@@ -2,7 +2,7 @@ import { Suspense } from 'react'
import { UncachedFetch, CachedData } from '../data-fetching' import { UncachedFetch, CachedData } from '../data-fetching'
import { PrivateCachedData } from './data-fetching' import { PrivateCachedData } from './data-fetching'
export const unstable_instant = true export const instant = true
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
const CACHE_KEY = '/private-cache/__LAYOUT__' const CACHE_KEY = '/private-cache/__LAYOUT__'
......
...@@ -2,7 +2,7 @@ import { Suspense } from 'react' ...@@ -2,7 +2,7 @@ import { Suspense } from 'react'
import { UncachedFetch, CachedData } from '../data-fetching' import { UncachedFetch, CachedData } from '../data-fetching'
import { ShortLivedCache } from './data-fetching' import { ShortLivedCache } from './data-fetching'
export const unstable_instant = true export const instant = true
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
const CACHE_KEY = __dirname + '/__LAYOUT__' const CACHE_KEY = __dirname + '/__LAYOUT__'
......
import { Suspense } from 'react' import { Suspense } from 'react'
import { UncachedFetch, CachedFetch, CachedData } from '../data-fetching' import { UncachedFetch, CachedFetch, CachedData } from '../data-fetching'
export const unstable_instant = true export const instant = true
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
const CACHE_KEY = __dirname + '/__LAYOUT__' const CACHE_KEY = __dirname + '/__LAYOUT__'
......
export const unstable_instant = true export const instant = true
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
export default async function Page() { export default async function Page() {
......
...@@ -2,7 +2,7 @@ import { Suspense } from 'react' ...@@ -2,7 +2,7 @@ import { Suspense } from 'react'
import { CachedData, getCachedData } from '../../data-fetching' import { CachedData, getCachedData } from '../../data-fetching'
import { cookies } from 'next/headers' import { cookies } from 'next/headers'
export const unstable_instant = true export const instant = true
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
const CACHE_KEY = __dirname + '/__PAGE__' const CACHE_KEY = __dirname + '/__PAGE__'
......
import { CachedData, getCachedData } from '../../data-fetching' import { CachedData, getCachedData } from '../../data-fetching'
export const unstable_instant = true export const instant = true
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
const CACHE_KEY = __dirname + '/__PAGE__' const CACHE_KEY = __dirname + '/__PAGE__'
......
import { Suspense } from 'react' import { Suspense } from 'react'
import { Static, Runtime, Dynamic } from '../shared' import { Static, Runtime, Dynamic } from '../shared'
export const unstable_instant = true export const instant = true
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
export default function Root({ children }: { children: React.ReactNode }) { export default function Root({ children }: { children: React.ReactNode }) {
......
...@@ -122,7 +122,7 @@ describe('Cache Components Errors - Client Components', () => { ...@@ -122,7 +122,7 @@ describe('Cache Components Errors - Client Components', () => {
https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data
- [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\` - [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\`
https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender
- [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route
at Client (app/client-awaited-io/client.tsx:6:19) at Client (app/client-awaited-io/client.tsx:6:19)
at Page (app/client-awaited-io/page.tsx:5:10) at Page (app/client-awaited-io/page.tsx:5:10)
...@@ -152,7 +152,7 @@ describe('Cache Components Errors - Client Components', () => { ...@@ -152,7 +152,7 @@ describe('Cache Components Errors - Client Components', () => {
https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data
- [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\` - [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\`
https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender
- [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route
at <unknown> (app/client-awaited-io/client.tsx:5:26) at <unknown> (app/client-awaited-io/client.tsx:5:26)
at body (<anonymous>) at body (<anonymous>)
...@@ -185,7 +185,7 @@ describe('Cache Components Errors - Client Components', () => { ...@@ -185,7 +185,7 @@ describe('Cache Components Errors - Client Components', () => {
https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data
- [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\` - [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\`
https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender
- [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route
at Client (webpack:///app/client-awaited-io/client.tsx:6:19) at Client (webpack:///app/client-awaited-io/client.tsx:6:19)
at Page (webpack:///app/client-awaited-io/page.tsx:5:10) at Page (webpack:///app/client-awaited-io/page.tsx:5:10)
...@@ -215,7 +215,7 @@ describe('Cache Components Errors - Client Components', () => { ...@@ -215,7 +215,7 @@ describe('Cache Components Errors - Client Components', () => {
https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data
- [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\` - [cache] For \`params\`: if the params are known, prerender them with \`generateStaticParams\`
https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender https://nextjs.org/docs/messages/blocking-prerender-runtime#for-known-params-prerender
- [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route
at a (<next-dist-dir>) at a (<next-dist-dir>)
at b (<next-dist-dir>) at b (<next-dist-dir>)
...@@ -299,7 +299,7 @@ describe('Cache Components Errors - Client Components', () => { ...@@ -299,7 +299,7 @@ describe('Cache Components Errors - Client Components', () => {
Ways to fix this: Ways to fix this:
- [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering - [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering
https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense
- [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route
at Client (app/client-use-search-params/client.tsx:6:18) at Client (app/client-use-search-params/client.tsx:6:18)
at Page (app/client-use-search-params/page.tsx:4:10) at Page (app/client-use-search-params/page.tsx:4:10)
...@@ -327,7 +327,7 @@ describe('Cache Components Errors - Client Components', () => { ...@@ -327,7 +327,7 @@ describe('Cache Components Errors - Client Components', () => {
Ways to fix this: Ways to fix this:
- [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering - [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering
https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense
- [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route
at <unknown> (app/client-use-search-params/client.tsx:6:3) at <unknown> (app/client-use-search-params/client.tsx:6:3)
at body (<anonymous>) at body (<anonymous>)
...@@ -361,7 +361,7 @@ describe('Cache Components Errors - Client Components', () => { ...@@ -361,7 +361,7 @@ describe('Cache Components Errors - Client Components', () => {
Ways to fix this: Ways to fix this:
- [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering - [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering
https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense
- [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route
at a (<next-dist-dir>) at a (<next-dist-dir>)
at b (<next-dist-dir>) at b (<next-dist-dir>)
...@@ -448,7 +448,7 @@ describe('Cache Components Errors - Client Components', () => { ...@@ -448,7 +448,7 @@ describe('Cache Components Errors - Client Components', () => {
Ways to fix this: Ways to fix this:
- [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering - [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering
https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense
- [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route
at Client (app/client-use-pathname/[id]/client.tsx:6:14) at Client (app/client-use-pathname/[id]/client.tsx:6:14)
at Page (app/client-use-pathname/[id]/page.tsx:4:10) at Page (app/client-use-pathname/[id]/page.tsx:4:10)
...@@ -476,7 +476,7 @@ describe('Cache Components Errors - Client Components', () => { ...@@ -476,7 +476,7 @@ describe('Cache Components Errors - Client Components', () => {
Ways to fix this: Ways to fix this:
- [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering - [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering
https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense
- [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route
at <unknown> (app/client-use-pathname/[id]/client.tsx:6:3) at <unknown> (app/client-use-pathname/[id]/client.tsx:6:3)
at body (<anonymous>) at body (<anonymous>)
...@@ -510,7 +510,7 @@ describe('Cache Components Errors - Client Components', () => { ...@@ -510,7 +510,7 @@ describe('Cache Components Errors - Client Components', () => {
Ways to fix this: Ways to fix this:
- [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering - [stream] Wrap the component in \`<Suspense fallback={...}>\` so the hook value streams in after prerendering
https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense https://nextjs.org/docs/messages/blocking-prerender-client-hook#wrap-in-or-move-into-suspense
- [block] Set \`export const unstable_instant = false\` to silence this warning and allow a blocking route - [block] Set \`export const instant = false\` to silence this warning and allow a blocking route
https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route https://nextjs.org/docs/messages/blocking-prerender-client-hook#allow-blocking-route
at a (<next-dist-dir>) at a (<next-dist-dir>)
at b (<next-dist-dir>) at b (<next-dist-dir>)
......
export const unstable_instant = false export const instant = false
export async function generateMetadata() { export async function generateMetadata() {
await new Promise((r) => setTimeout(r, 0)) await new Promise((r) => setTimeout(r, 0))
...@@ -10,13 +10,13 @@ export default async function Page() { ...@@ -10,13 +10,13 @@ export default async function Page() {
<> <>
<p> <p>
This page is static except for `generateMetadata`. It opts into a fully This page is static except for `generateMetadata`. It opts into a fully
dynamic, blocking route via `export const unstable_instant = false`. dynamic, blocking route via `export const instant = false`. That opt-in
That opt-in is a synonym for wrapping the document body in a Suspense is a synonym for wrapping the document body in a Suspense boundary — it
boundary — it says the user accepts a blocking route — but it is NOT a says the user accepts a blocking route — but it is NOT a documented
documented mitigation for dynamic `generateMetadata`. So even with the mitigation for dynamic `generateMetadata`. So even with the opt-in, we
opt-in, we still expect the dynamic-metadata error to be shown to nudge still expect the dynamic-metadata error to be shown to nudge users back
users back toward making `generateMetadata` static (or, secondarily, toward making `generateMetadata` static (or, secondarily, making the
making the page partially dynamic). page partially dynamic).
</p> </p>
<span id="sentinel">sentinel</span> <span id="sentinel">sentinel</span>
</> </>
......
export const unstable_instant = false export const instant = false
export async function generateViewport() { export async function generateViewport() {
await new Promise((r) => setTimeout(r, 0)) await new Promise((r) => setTimeout(r, 0))
...@@ -10,10 +10,10 @@ export default async function Page() { ...@@ -10,10 +10,10 @@ export default async function Page() {
<> <>
<p> <p>
This page is static except for `generateViewport`. It opts into a fully This page is static except for `generateViewport`. It opts into a fully
dynamic, blocking route via `export const unstable_instant = false`, dynamic, blocking route via `export const instant = false`, which is a
which is a documented mitigation for dynamic `generateViewport`. With documented mitigation for dynamic `generateViewport`. With that opt-in,
that opt-in, the dynamic viewport should not error the build and should the dynamic viewport should not error the build and should not show a
not show a redbox in dev. This is the symmetric counterpart to the redbox in dev. This is the symmetric counterpart to the
Suspense-above-body opt-in. Suspense-above-body opt-in.
</p> </p>
<span id="sentinel">sentinel</span> <span id="sentinel">sentinel</span>
......
import { notFound } from 'next/navigation' import { notFound } from 'next/navigation'
export const unstable_instant = false export const instant = false
export function generateStaticParams() { export function generateStaticParams() {
return [{ slug: 'not-found' }] return [{ slug: 'not-found' }]
......
import { Suspense } from 'react' import { Suspense } from 'react'
import { connection } from 'next/server' import { connection } from 'next/server'
export const unstable_instant = { export const instant = {
unstable_samples: [{ searchParams: { myParam: 'testValue' } }], unstable_samples: [{ searchParams: { myParam: 'testValue' } }],
} }
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
......
...@@ -4,7 +4,7 @@ import { Suspense } from 'react' ...@@ -4,7 +4,7 @@ import { Suspense } from 'react'
// this route opts into runtime prefetching. The prefetch therefore includes // this route opts into runtime prefetching. The prefetch therefore includes
// the resolved `slug`, so the param should be visible inside the instant // the resolved `slug`, so the param should be visible inside the instant
// scope instead of suspending. // scope instead of suspending.
export const unstable_instant: { export const instant: {
unstable_samples: Array<{ params: { slug: string } }> unstable_samples: Array<{ params: { slug: string } }>
} = { } = {
unstable_samples: [{ params: { slug: 'anything' } }], unstable_samples: [{ params: { slug: 'anything' } }],
......
...@@ -93,7 +93,8 @@ describe('instant-navigation-testing-api', () => { ...@@ -93,7 +93,8 @@ describe('instant-navigation-testing-api', () => {
) )
}) })
it('renders runtime-prefetched content instantly during navigation', async () => { // TODO: This has been flaky in CI for weeks and needs further investigation.
it.skip('renders runtime-prefetched content instantly during navigation', async () => {
const page = await openPage(next, '/') const page = await openPage(next, '/')
await instant(page, async () => { await instant(page, async () => {
...@@ -300,7 +301,7 @@ describe('instant-navigation-testing-api', () => { ...@@ -300,7 +301,7 @@ describe('instant-navigation-testing-api', () => {
// behind a Suspense boundary until the instant lock is released. // behind a Suspense boundary until the instant lock is released.
// //
// Each test route reads a different runtime param inside a <Suspense> // Each test route reads a different runtime param inside a <Suspense>
// boundary without opting into `unstable_instant: { prefetch: 'runtime' }`. // boundary without opting into `instant: { prefetch: 'runtime' }`.
// During the instant scope, the static page title should be visible and the // During the instant scope, the static page title should be visible and the
// Suspense fallback should be shown, but the resolved param value should // Suspense fallback should be shown, but the resolved param value should
// NOT be present. // NOT be present.
......
import { Instant } from 'next' import { Instant } from 'next'
import { ThrowsInClient } from './client' import { ThrowsInClient } from './client'
export const unstable_instant: Instant = { export const instant: Instant = {
level: 'experimental-error', level: 'experimental-error',
unstable_samples: [{ searchParams: {} }], unstable_samples: [{ searchParams: {} }],
} }
......
import { Instant } from 'next' import { Instant } from 'next'
import { ThrowsInClient } from './client' import { ThrowsInClient } from './client'
export const unstable_instant: Instant = { export const instant: Instant = {
level: 'experimental-error', level: 'experimental-error',
unstable_samples: [{ searchParams: {} }], unstable_samples: [{ searchParams: {} }],
} }
......
...@@ -2,7 +2,7 @@ import { cookies } from 'next/headers' ...@@ -2,7 +2,7 @@ import { cookies } from 'next/headers'
import { Suspense } from 'react' import { Suspense } from 'react'
import { ensureThrows } from '../../../../ensure-error' import { ensureThrows } from '../../../../ensure-error'
export const unstable_instant = { level: 'experimental-error' } export const instant = { level: 'experimental-error' }
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
export default async function Page() { export default async function Page() {
......
...@@ -2,7 +2,7 @@ import { cookies } from 'next/headers' ...@@ -2,7 +2,7 @@ import { cookies } from 'next/headers'
import { Suspense } from 'react' import { Suspense } from 'react'
import { ensureThrows } from '../../../../ensure-error' import { ensureThrows } from '../../../../ensure-error'
export const unstable_instant = { level: 'experimental-error' } export const instant = { level: 'experimental-error' }
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
export default async function Page() { export default async function Page() {
......
...@@ -2,7 +2,7 @@ import { cookies } from 'next/headers' ...@@ -2,7 +2,7 @@ import { cookies } from 'next/headers'
import { Suspense } from 'react' import { Suspense } from 'react'
import { ensureThrows } from '../../../../ensure-error' import { ensureThrows } from '../../../../ensure-error'
export const unstable_instant = { level: 'experimental-error' } export const instant = { level: 'experimental-error' }
export const prefetch = 'allow-runtime' export const prefetch = 'allow-runtime'
export default async function Page() { export default async function Page() {
......
...@@ -4,7 +4,7 @@ import assert from 'node:assert' ...@@ -4,7 +4,7 @@ import assert from 'node:assert'
import { Suspense } from 'react' import { Suspense } from 'react'
export const unstable_instant: Instant = { export const instant: Instant = {
level: 'experimental-error', level: 'experimental-error',
unstable_samples: [ unstable_samples: [
{ {
......
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment