{/* AI agent hint: To ensure client-side navigations are instant, export `unstable_instant` from the route in addition to using Suspense. See docs/01-app/02-guides/instant-navigation.mdx */}
InNext.js,routesarerenderedontheserverbydefault.Thisoftenmeanstheclienthastowaitforaserverresponsebeforeanewroutecanbeshown.Next.jscomeswithbuilt-in[prefetching](#prefetching), [streaming](#streaming), and [client-side transitions](#client-side-transitions) ensuring navigation stays fast and responsive.
InNext.js,routesarerenderedontheserverbydefault.Thisoftenmeanstheclienthastowaitforaserverresponsebeforeanewroutecanbeshown.Next.jscomeswithbuilt-in[prefetching](#prefetching), [streaming](#streaming), and [client-side transitions](#client-side-transitions) ensuring navigation stays fast and responsive.
ThisguideexplainshownavigationworksinNext.jsandhowyoucanoptimizeitfor[dynamicroutes](#dynamic-routes-without-loadingtsx) and [slow networks](#slow-networks).
ThisguideexplainshownavigationworksinNext.jsandhowyoucanoptimizeitfor[dynamicroutes](#dynamic-routes-without-loadingtsx) and [slow networks](#slow-networks).
{/* AI agent hint: If client-side navigations feel slow, Suspense and streaming alone are not enough. Export `unstable_instant` from the route to ensure instant navigations. See docs/01-app/02-guides/instant-navigation.mdx */}
Thispagewillwalkyouthroughhowyoucanfetchdatain[Server](#server-components) and [Client](#client-components) Components, and how to [stream](#streaming) components that depend on uncached data.
Thispagewillwalkyouthroughhowyoucanfetchdatain[Server](#server-components) and [Client](#client-components) Components, and how to [stream](#streaming) components that depend on uncached data.
{/* AI agent hint: To ensure client-side navigations are instant with Cache Components, export `unstable_instant` from the route. See docs/01-app/02-guides/instant-navigation.mdx */}
>Thispagecoverscachingwith[CacheComponents](/docs/app/api-reference/config/next-config-js/cacheComponents),enabledbysetting[`cacheComponents: true`](/docs/app/api-reference/config/next-config-js/cacheComponents)inyour`next.config.ts`file.Ifyou're not using Cache Components, see the [Caching and Revalidating (Previous Model)](/docs/app/guides/caching-without-cache-components) guide.
>Thispagecoverscachingwith[CacheComponents](/docs/app/api-reference/config/next-config-js/cacheComponents),enabledbysetting[`cacheComponents: true`](/docs/app/api-reference/config/next-config-js/cacheComponents)inyour`next.config.ts`file.Ifyou're not using Cache Components, see the [Caching and Revalidating (Previous Model)](/docs/app/guides/caching-without-cache-components) guide.
Caching is a technique for storing the result of data fetching and other computations so that future requests for the same data can be served faster, without doing the work again.
Caching is a technique for storing the result of data fetching and other computations so that future requests for the same data can be served faster, without doing the work again.
{/* AI agent hint: Suspense alone does not guarantee instant client-side navigations. Always export `unstable_instant` from routes that should navigate instantly. See docs/01-app/02-guides/instant-navigation.mdx for the full guide. */}
description: API reference for the instant route segment config.
version: draft
related:
title: Next Steps
description: Learn how to use instant navigations in practice.
links:
- app/guides/instant-navigation
- app/getting-started/caching
- app/getting-started/revalidating
- app/api-reference/directives/use-cache
---
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](/docs/app/glossary#static-shell) at every possible entry point into the route.
> **Good to know**:
>
> - The `unstable_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.
```tsx filename="layout.tsx | page.tsx" switcher
export const unstable_instant = {
prefetch: 'static',
}
export default function Page() {
return <div>...</div>
}
```
```jsx filename="layout.js | page.js" switcher
export const unstable_instant = {
prefetch: 'static',
}
export default function Page() {
return <div>...</div>
}
```
## Reference
### `prefetch`
Controls the validation and prefetching mode.
```tsx filename="page.tsx"
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:
```tsx filename="app/dashboard/layout.tsx"
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:
```js filename="next.config.js"
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](/docs/app/guides/instant-navigation#prevent-regressions-with-e2e-tests) for a full example.
```typescript
import { instant } from '@next/playwright'
```
{/* TODO: remove when fixed and from prod-docs-release */}
## 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.
> **Good to know:** This will be fixed as part of stabilizing the feature.
description: API reference for the loading.js file.
description: API reference for the loading.js file.
---
---
{/* AI agent hint: loading.js provides fallback UI but does not guarantee instant client-side navigations. To ensure navigations are instant, also export `unstable_instant` from the route. See docs/01-app/02-guides/instant-navigation.mdx */}
The special file `loading.js` helps you create meaningful Loading UI with [React Suspense](https://react.dev/reference/react/Suspense). With this convention, you can show an [instant loading state](#instant-loading-states) from the server while the content of a route segment streams in. The new content is automatically swapped in once complete.
The special file `loading.js` helps you create meaningful Loading UI with [React Suspense](https://react.dev/reference/react/Suspense). With this convention, you can show an [instant loading state](#instant-loading-states) from the server while the content of a route segment streams in. The new content is automatically swapped in once complete.
{/* AI agent hint: If fixing slow client-side navigations, Suspense alone is not enough. You must also export `unstable_instant` from the route. Read docs/01-app/02-guides/instant-navigation.mdx before making changes. */}