instant

The unstable_instant route segment config opts a route into validation for instant client-side navigations. Next.js checks, during development and at build time, that the caching structure produces an instant static shell at every possible entry point into the route.

export const unstable_instant = {
  prefetch: 'static',
}
 
export default function Page() {
  return <div>...</div>
}

Reference

prefetch

Controls the validation and prefetching mode.

export const unstable_instant = {
  prefetch: 'static',
}

• 'static': Enables validation. Prefetching behavior stays the same (static by default). Components that read cookies or headers are treated as dynamic and must be behind Suspense.

Disabling instant

Set false to exempt a segment from validation:

export const unstable_instant = false

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 at build time. Errors appear in the dev error overlay or fail the build.

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.

Inspecting loading states

Enable the DevTools toggle with the experimental flag:

module.exports = {
  experimental: {
    instantNavigationDevToolsToggle: true,
  },
}

Open the Next.js DevTools and select Instant Navs. Two options are available:

• Page load: click Reload to refresh the page and freeze it at the initial static UI that was generated for this route, before any dynamic data streams in.
• Client navigation: once enabled, clicking any link in your app shows the prefetched UI for that page instead of the full result.

Use both to check that your loading states look right on first visit and on navigation.

Testing instant navigation

The @next/playwright package exports an instant() helper that holds back dynamic content while the callback runs against the static shell. See the guide for a full example.

import { instant } from '@next/playwright'

Known issue: shared cookie across projects

The DevTools use a next-instant-navigation-testing cookie to freeze the UI at the static shell. Because cookies are scoped to the domain and not the port, running multiple projects on the same domain (typically localhost) means the cookie is shared across them and can cause unexpected behavior. Clear the cookie or close the Instant Navs panel when switching between projects to avoid issues.

TypeScript

type RuntimeSample = {
  cookies?: Array<{ name: string; value: string }>
  headers?: Array<[string, string]>
  params?: Record<string, string | string[]>
  searchParams?: Record<string, string | string[]>
}
 
type InstantConfig =
  | false
  | {
      prefetch: 'static'
      from?: string[]
      unstable_disableValidation?: boolean
    }
  | {
      prefetch: 'runtime'
      samples: RuntimeSample[]
      from?: string[]
      unstable_disableValidation?: boolean
    }
 
export const unstable_instant: InstantConfig = {
  prefetch: 'static',
}

Version History