# Technical Documentation: vercel/next.js > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/vercel/next.js) ### Index (`docs/index.mdx`) --- title: Next.js Docs description: Welcome to the Next.js Documentation. related: title: Next Steps description: Create your first application and learn the core Next.js features. links: - app/getting-started --- Welcome to the Next.js documentation! ## What is Next.js? Next.js is a React framework for building full-stack web applications. You use React Components to build user interfaces, and Next.js for additional features and optimizations. It also automatically configures lower-level tools like bundlers and compilers. You can instead focus on building your product and shipping quickly. Whether you're an individual developer or part of a larger team, Next.js can help you build interactive, dynamic, and fast React applications. ## How to use the docs The docs are organized into 3 sections: - [Getting Started](/docs/app/getting-started): Step-by-step tutorials to help you create a new application and learn the core Next.js features. - [Guides](/docs/app/guides): Tutorials on specific use cases, choose what's relevant to you. - [API Reference](/docs/app/api-reference): Detailed technical reference for every feature. Use the sidebar to navigate through the sections, or search (`Ctrl+K` or `Cmd+K`) to quickly find a page. ## App Router and Pages Router Next.js has two different routers: - **App Router**: The newer router that supports new React features like Server Components. - **Pages Router**: The original router, still supported and being improved. At the top of the sidebar, you'll notice a dropdown menu that allows you to switch between the [App Router](/docs/app) and the [Pages Router](/docs/pages) docs. ### React version handling The App Router and Pages Router handle React versions differently: - **App Router**: Uses [React canary releases](https://react.dev/blog/2023/05/03/react-canaries) built-in, which include all the stable React 19 changes, as well as newer features being validated in frameworks, prior to a new React release. - **Pages Router**: Uses the React version installed in your project's `package.json`. This approach ensures new React features work reliably in the App Router while maintaining backwards compatibility for existing Pages Router applications. ## Pre-requisite knowledge Our documentation assumes some familiarity with web development. Before getting started, it'll help if you're comfortable with: - HTML - CSS - JavaScript - React If you're new to React or need a refresher, we recommend starting with our [React Foundations course](/learn/react-foundations), and the [Next.js Foundations course](/learn/dashboard-app) that has you building an application as you learn. ## Accessibility For the best experience when using a screen reader, we recommend using Firefox and NVDA, or Safari and VoiceOver. ## Join our Community If you have questions about anything related to Next.js, you're always welcome to ask our community on [GitHub Discussions](https://github.com/vercel/next.js/discussions), [Discord](https://discord.com/invite/bUG2bvbtHy), [X (Twitter)](https://x.com/nextjs), and [Reddit](https://www.reddit.com/r/nextjs). --- ### 01 App Index (`docs/01-app/index.mdx`) --- title: App Router description: The App Router is a file-system based router that uses React's latest features such as Server Components, Suspense, Server Functions, and more. related: title: Next Steps description: Learn the fundamentals of building an App Router project, from installation to layouts, navigation, server and client components. links: - app/getting-started/installation - app/getting-started/project-structure - app/getting-started/layouts-and-pages - app/getting-started/linking-and-navigating - app/getting-started/server-and-client-components --- The **App Router** is a file-system based router that uses React's latest features such as [Server Components](https://react.dev/reference/rsc/server-components), [Suspense](https://react.dev/reference/react/Suspense), and [Server Functions](https://react.dev/reference/rsc/server-functions). --- ### 02 Pages Index (`docs/02-pages/index.mdx`) --- title: Pages Router description: Before Next.js 13, the Pages Router was the main way to create routes in Next.js with an intuitive file-system router. --- > You're viewing the documentation for the Pages Router. See the [App Router](/docs/app) documentation for the latest features. The **Pages Router** uses an intuitive file-system router to map each file to a route. Before Next.js 13, the Pages Router was the main way to create routes in Next.js. It's still supported in newer versions of Next.js, but we recommend migrating to the new [App Router](/docs/app) to leverage React's latest features. --- ### 03 Architecture Index (`docs/03-architecture/index.mdx`) --- title: Architecture description: How Next.js Works --- Learn about the Next.js architecture and how it works under the hood. --- ### 04 Community Index (`docs/04-community/index.mdx`) --- title: Next.js Community nav_title: Community description: Get involved in the Next.js community. --- With over 5 million weekly downloads, Next.js has a large and active community of developers across the world. Here's how you can get involved in our community: ## Contributing There are a couple of ways you can contribute to the development of Next.js: - [Documentation](/docs/community/contribution-guide): Suggest improvements or even write new sections to help our users understand how to use Next.js. - [Examples](https://github.com/vercel/next.js/tree/canary/examples): Help developers integrate Next.js with other tools and services by creating a new example or improving an existing one. - [Codebase](https://github.com/vercel/next.js/tree/canary/contributing/core): Learn more about the underlying architecture, contribute to bug fixes, errors, and suggest new features. ## Discussions If you have a question about Next.js, or want to help others, you're always welcome to join the conversation: - [GitHub Discussions](https://github.com/vercel/next.js/discussions) - [Discord](https://discord.com/invite/bUG2bvbtHy) - [Reddit](https://www.reddit.com/r/nextjs) ## Social Media Follow Next.js on [Twitter](https://x.com/nextjs) for the latest updates, and subscribe to the [Vercel YouTube channel](https://www.youtube.com/@VercelHQ) for Next.js videos. ## Code of Conduct We believe in creating an inclusive, welcoming community. As such, we ask all members to adhere to our [Code of Conduct](https://github.com/vercel/next.js/blob/canary/CODE_OF_CONDUCT.md). This document outlines our expectations for participant behavior. We invite you to read it and help us maintain a safe and respectful environment. --- ### 01 App 01 Getting Started Index (`docs/01-app/01-getting-started/index.mdx`) --- title: Getting Started description: Learn how to create full-stack web applications with the Next.js App Router. --- Welcome to the Next.js documentation! This **Getting Started** section will help you create your first Next.js app and learn the core features you'll use in every project. ## Pre-requisite knowledge Our documentation assumes some familiarity with web development. Before getting started, it'll help if you're comfortable with: - HTML - CSS - JavaScript - React If you're new to React or need a refresher, we recommend starting with our [React Foundations course](/learn/react-foundations), and the [Next.js Foundations course](/learn/dashboard-app) that has you building an application as you learn. ## Next Steps --- ### 01 App 02 Guides Index (`docs/01-app/02-guides/index.mdx`) --- title: Guides description: Learn how to implement common patterns and real-world use cases using Next.js --- --- ### 01 App 03 Api Reference Index (`docs/01-app/03-api-reference/index.mdx`) --- title: API Reference description: Next.js API Reference for the App Router. --- --- ### 02 Pages 01 Getting Started Index (`docs/02-pages/01-getting-started/index.mdx`) --- title: Getting Started - Pages Router nav_title: Getting Started description: Learn how to create full-stack web applications with Next.js with the Pages Router. --- --- ### 02 Pages 02 Guides Index (`docs/02-pages/02-guides/index.mdx`) --- title: Guides description: Learn how to implement common UI patterns and use cases using Next.js --- --- ### 02 Pages 03 Building Your Application Index (`docs/02-pages/03-building-your-application/index.mdx`) --- title: Building Your Application description: Learn how to use Next.js features to build your application. --- --- ### 02 Pages 04 Api Reference Index (`docs/02-pages/04-api-reference/index.mdx`) --- title: API Reference description: Next.js API Reference for the Pages Router. --- --- ### 01 App 02 Guides Client Side Data Fetching Index (`docs/01-app/02-guides/client-side-data-fetching/index.mdx`) --- title: Client-side data fetching description: Fetch data in Client Components with a data-fetching library, optionally provide initial data from a Server Component, and coordinate server and client caches. related: description: Related guides and references. links: - app/getting-started/fetching-data - app/guides/single-page-applications - app/guides/interactive-apps - app/getting-started/caching --- Many apps can provide responsive interactions without a client data-fetching library. If a Client Component only needs to read server data once, [pass it a Promise and unwrap it with React's `use()`](/docs/app/getting-started/fetching-data#streaming-data-with-the-use-api). This avoids adding a library for data that never revalidates on the client. See [Building interactive apps](/docs/app/guides/interactive-apps) for patterns using Server Functions, transitions, optimistic UI, and pending feedback. Use a client data-fetching library such as [SWR](https://swr.vercel.app), [TanStack Query](https://tanstack.com/query), or [Apollo Client](https://www.apollographql.com/docs/react) when Client Components need a shared browser cache. These libraries can add focus revalidation, interval polling, request deduplication, or optimistic updates across components. ## Choose a client fetching pattern First decide whether the initial view needs data from the server or can wait for a browser request after hydration. Client data-fetching libraries support three common patterns: | Pattern | SWR | TanStack Query | When data becomes available | | ----------------------- | ------------------------------ | --------------------- | -------------------------------------- | | Inline loading states | `useSWR` | `useQuery` | Browser request after hydration | | Suspense loading states | `useSWR` with `suspense: true` | `useSuspenseQuery` | Browser request after hydration | | Provided by the server | `` | `` | Initial render or streamed from server | Use inline loading states when each component should render its own loading UI. Use [Suspense](/docs/app/getting-started/fetching-data#streaming) to define loading UI at a boundary and coordinate which parts of the interface reveal together or progressively. For client-only fetching, choose the pattern that matches the loading experience you want. Suspense coordinates rendering, while the data library and component structure determine when requests start. For browser-driven interactions such as autocomplete, you can use either client-only pattern. The initial result waits for hydration and a browser request, which is often the right tradeoff for data that is not needed until an interaction. Provide initial data from a [Server Component](/docs/app/getting-started/server-and-client-components) when the server knows what the initial render needs. The value can be included in the initial render or streamed through Suspense. The library receives it in the React Server Component payload and can continue managing it in the browser. ## Cache server data with Cache Components (optional) Providing initial data and caching it on the server are independent choices. Add Cache Components when the server read or rendered view should be reused. When both are enabled, three cache layers can hold related data: | Layer | What it stores | Freshness control | | ---------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Next.js server cache | Cached data and Server Component output | [`cacheLife`](/docs/app/api-reference/functions/cacheLife) `revalidate` and `expire` | | Next.js client cache | React Server Component payloads for visited and prefetched routes | [`cacheLife`](/docs/app/api-reference/functions/cacheLife) `stale` | | Client data-fetching library | Browser data stored under an SWR key or TanStack query key | The library's revalidation options and mutations | Next.js [prefetching](/docs/app/guides/prefetching) can place a route's React Server Component payload in the client cache before navigation. The cache layers keep independent freshness policies and do not need matching durations. Cache identities and mutation invalidation must stay coordinated across layers. ## Coordinate mutations Server Components, data-fetching libraries, and mutations manage different parts of the data flow: - **Server Components** provide the initial data, scoped to the segment that owns it. - **The data-fetching library** stores the browser value under a shared cache identity. - **Mutations** can update the browser cache immediately and invalidate cached server data so the next render can read a fresh value. An optimistic update should restore the previous browser value if the write fails. If the server read is not cached, there is no server tag to invalidate. After a mutation, invalidate any cached server read that provided the initial data: | Method | Use when | Next server read | | -------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------ | | [`updateTag(tag)`](/docs/app/api-reference/functions/updateTag) | A Server Action must make its update visible immediately | Waits for fresh data | | [`revalidateTag(tag, 'max')`](/docs/app/api-reference/functions/revalidateTag) | The update is passive or stale data is acceptable | Serves stale data while revalidating | | [`revalidateTag(tag, { expire: 0 })`](/docs/app/api-reference/functions/revalidateTag) | A webhook or external system requires immediate expiration | Waits for fresh data | ## Apply these patterns with SWR or TanStack Query - [Client-side data fetching with SWR](/docs/app/guides/client-side-data-fetching/swr) - [Client-side data fetching with TanStack Query](/docs/app/guides/client-side-data-fetching/tanstack-query) See both patterns in the live [`next-spa-patterns` demo](https://next-spa-patterns.labs.vercel.dev) and its [source code](https://github.com/vercel-labs/next-spa-patterns). --- ### 01 App 02 Guides Migrating Index (`docs/01-app/02-guides/migrating/index.mdx`) --- title: Migrating description: Learn how to migrate from popular frameworks to Next.js --- --- ### 01 App 02 Guides Testing Index (`docs/01-app/02-guides/testing/index.mdx`) --- title: Testing description: Learn how to set up Next.js with four commonly used testing tools — Cypress, Playwright, Vitest, and Jest. --- In React and Next.js, there are a few different types of tests you can write, each with its own purpose and use cases. This page provides an overview of types and commonly used tools you can use to test your application. ## Types of tests - **Unit Testing** involves testing individual units (or blocks of code) in isolation. In React, a unit can be a single function, hook, or component. - **Component Testing** is a more focused version of unit testing where the primary subject of the tests is React components. This may involve testing how components are rendered, their interaction with props, and their behavior in response to user events. - **Integration Testing** involves testing how multiple units work together. This can be a combination of components, hooks, and functions. - **End-to-End (E2E) Testing** involves testing user flows in an environment that simulates real user scenarios, like the browser. This means testing specific tasks (e.g. signup flow) in a production-like environment. - **Snapshot Testing** involves capturing the rendered output of a component and saving it to a snapshot file. When tests run, the current rendered output of the component is compared against the saved snapshot. Changes in the snapshot are used to indicate unexpected changes in behavior. ## Async Server Components Since `async` Server Components are new to the React ecosystem, some tools do not fully support them. In the meantime, we recommend using **End-to-End Testing** over **Unit Testing** for `async` components. ## Guides See the guides below to learn how to set up Next.js with these commonly used testing tools: --- ### 01 App 02 Guides Upgrading Index (`docs/01-app/02-guides/upgrading/index.mdx`) --- title: Upgrade Guides nav_title: Upgrading description: Learn how to upgrade to the latest versions of Next.js. --- Learn how to upgrade Next.js, with a coding agent or by following a version-specific guide: --- ### 01 App 03 Api Reference 01 Directives Index (`docs/01-app/03-api-reference/01-directives/index.mdx`) --- title: Directives description: Learn how React and Next.js directives define client entry points, Server Functions, and cached output. --- Directives are string literals that tell the compiler and bundler how to treat the code around them. On their own, directives look like plain strings, but Next.js and React read them as instructions that transform the code they cover. A directive can create a client entry point or a Server Function, or cache a function's or component's output. | Directive | Defined by | Effect | | --------------------------------------------------------------- | ---------- | --------------------------------------------------- | | [`'use client'`](/docs/app/api-reference/directives/use-client) | React | Creates a client entry point from Server Components | | [`'use server'`](/docs/app/api-reference/directives/use-server) | React | Exposes server-side functions as Server Functions | | [`'use cache'`](/docs/app/api-reference/directives/use-cache) | Next.js | Caches and reuses output based on the code's inputs | The `'use cache'` directive also has [`'use cache: remote'`](/docs/app/api-reference/directives/use-cache-remote) and [`'use cache: private'`](/docs/app/api-reference/directives/use-cache-private) variants. Configure custom [cache handlers](/docs/app/api-reference/config/next-config-js/cacheHandlers) to control where cached entries are stored. > **Good to know:** Next.js applies directives during compilation in both development and production. > > The error overlay, indicators, and stack traces point to your source file and line rather than the generated output. ## Where to place a directive The `'use client'` directive must appear at the top of a file, before any imports. It applies to the entire module and defines a file-wide boundary because the module is bundled and shipped to the browser. You cannot use `'use client'` inline. Place `'use server'` or `'use cache'` at the top of a file to apply the directive to every export. Place either directive at the top of a function to apply it only to that function. ```ts filename="app/data.ts" switcher // File-level: applies to every export 'use cache' export async function getUser(id: string) { return { id } } ``` ```js filename="app/data.js" switcher // File-level: applies to every export 'use cache' export async function getUser(id) { return { id } } ``` ```tsx filename="app/user.tsx" switcher // Function-level: applies to this function only export async function User() { 'use cache' return

User

} ``` ```jsx filename="app/user.js" switcher // Function-level: applies to this function only export async function User() { 'use cache' return

User

} ``` Declare `'use server'` and `'use cache'` in server modules, not in a `'use client'` module. To import a `'use server'` or `'use cache'` function into a Client Component, place the directive at the top of the server module. The Client Component receives a reference that invokes the function on the server. Place the directive inside a function when it should apply only to that function or component. When it should apply to several exported functions, place it at the top of the file instead of repeating it. Every exported function covered by a file-level `'use server'` or `'use cache'` directive must be `async`. ## What each directive requires A directive imposes rules on the code it covers: - **`'use client'`** marks its exports as the boundary between server and client. Client Component props that cross the boundary must be [serializable](https://react.dev/reference/rsc/use-client#serializable-types). Ordinary functions, such as event handlers, cannot cross, but Server Functions can cross as references. - **`'use server'`** marks the functions it covers as [Server Functions](/docs/app/glossary#server-function). Server Functions must be `async`. When invoked from a Client Component, their arguments and return values are serialized across the network. The Client Component receives a reference that invokes the function on the server, not the function's code. - **`'use cache'`** caches the output of the functions or components it covers based on their inputs. Cached functions and components must be `async`. Their arguments and return values must be serializable, except for non-serializable values that the cached code passes through without inspecting. Cached code cannot read request-time APIs like `cookies()`, `headers()`, or `searchParams` directly. With `'use cache'` at the top of a page or layout file, exported functions such as `generateMetadata` and `generateStaticParams` must be `async`. ## Placement decides what you cache With `'use cache'`, placement determines the scope of a cache entry. A directive at the top of a page caches the page's output and the components it imports. The same directive inside a data function caches only that function's result. When one data request performs the expensive work, cache that function instead of the page. With [`'use cache: remote'`](/docs/app/api-reference/directives/use-cache-remote), a remote cache handler stores entries. Larger entries can increase storage and network costs. --- ### 01 App 03 Api Reference 02 Components Index (`docs/01-app/03-api-reference/02-components/index.mdx`) --- title: Components description: API Reference for Next.js built-in components. --- {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} --- ### 01 App 03 Api Reference 03 File Conventions Index (`docs/01-app/03-api-reference/03-file-conventions/index.mdx`) --- title: File-system conventions description: API Reference for Next.js file-system conventions. --- --- ### 01 App 03 Api Reference 04 Functions Index (`docs/01-app/03-api-reference/04-functions/index.mdx`) --- title: Functions description: API Reference for Next.js Functions and Hooks. --- {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} --- ### 01 App 03 Api Reference 05 Config Index (`docs/01-app/03-api-reference/05-config/index.mdx`) --- title: Configuration description: Learn how to configure Next.js applications. --- --- ### 01 App 03 Api Reference 06 Cli Index (`docs/01-app/03-api-reference/06-cli/index.mdx`) --- title: CLI description: API Reference for the Next.js Command Line Interface (CLI) tools. --- {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} Next.js comes with **two** Command Line Interface (CLI) tools: - **`create-next-app`**: Quickly create a new Next.js application using the default template or an [example](https://github.com/vercel/next.js/tree/canary/examples) from a public GitHub repository. - **`next`**: Run the Next.js development server, build your application, and more. --- ### 01 App 03 Api Reference 07 Adapters Index (`docs/01-app/03-api-reference/07-adapters/index.mdx`) --- title: Adapters description: Build deployment adapters for Next.js platforms and infrastructure. --- Use this section to build and validate deployment adapters that integrate with the Next.js build and runtime model. --- ### 02 Pages 02 Guides Migrating Index (`docs/02-pages/02-guides/migrating/index.mdx`) --- title: Migrating description: Learn how to migrate from popular frameworks to Next.js --- --- ### 02 Pages 02 Guides Testing Index (`docs/02-pages/02-guides/testing/index.mdx`) --- title: Testing description: Learn how to set up Next.js with three commonly used testing tools — Cypress, Playwright, Vitest, and Jest. source: app/guides/testing --- {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} --- ### 02 Pages 02 Guides Upgrading Index (`docs/02-pages/02-guides/upgrading/index.mdx`) --- title: Upgrading description: Learn how to upgrade to the latest versions of Next.js. --- To have a coding agent perform and verify an upgrade, run `npx next@canary upgrade --agent=latest`. See [Upgrade with a coding agent](/docs/app/guides/upgrading/agent-upgrade) for details. To upgrade manually, follow a version-specific guide: --- ### 02 Pages 03 Building Your Application 01 Routing Index (`docs/02-pages/03-building-your-application/01-routing/index.mdx`) --- title: Routing description: Learn the fundamentals of routing for front-end applications with the Pages Router. --- The Pages Router has a file-system based router built on concepts of pages. When a file is added to the `pages` directory it's automatically available as a route. Learn more about routing in the Pages Router: --- ### 02 Pages 03 Building Your Application 02 Rendering Index (`docs/02-pages/03-building-your-application/02-rendering/index.mdx`) --- title: Rendering description: Learn the fundamentals of rendering in React and Next.js. --- By default, Next.js **prerenders** every page. This means that Next.js generates HTML for each page in advance, instead of having it all done by client-side JavaScript. Prerendering can result in better performance and SEO. Each generated HTML is associated with minimal JavaScript code necessary for that page. When a page is loaded by the browser, its JavaScript code runs and makes the page fully interactive (this process is called [hydration](https://react.dev/reference/react-dom/client/hydrateRoot) in React). ### Prerendering Next.js has two forms of prerendering: **Static Generation** and **Server-side Rendering**. The difference is in **when** it generates the HTML for a page. - Static Generation: The HTML is generated at **build time** and will be reused on each request. - Server-side Rendering: The HTML is generated on **each request**. Importantly, Next.js lets you choose which prerendering form you'd like to use for each page. You can create a "hybrid" Next.js app by using Static Generation for most pages and using Server-side Rendering for others. We recommend using Static Generation over Server-side Rendering for performance reasons. Statically generated pages can be cached by CDN with no extra configuration to boost performance. However, in some cases, Server-side Rendering might be the only option. You can also use client-side data fetching along with Static Generation or Server-side Rendering. That means some parts of a page can be rendered entirely by clientside JavaScript. To learn more, take a look at the [Data Fetching](/docs/pages/building-your-application/data-fetching/client-side) documentation. --- ### 02 Pages 03 Building Your Application 03 Data Fetching Index (`docs/02-pages/03-building-your-application/03-data-fetching/index.mdx`) --- title: Data Fetching description: Next.js allows you to fetch data in multiple ways, with prerendering, server-side rendering or static-site generation, and incremental static regeneration. Learn how to manage your application data in Next.js. --- Data fetching in Next.js allows you to render your content in different ways, depending on your application's use case. These include prerendering with **Server-side Rendering** or **Static Generation**, and updating or creating content at runtime with **Incremental Static Regeneration**. ## Examples - [Agility CMS Example](https://github.com/vercel/next.js/tree/canary/examples/cms-agilitycms) ([Demo](https://next-blog-agilitycms.vercel.app/)) - [Builder.io Example](https://github.com/vercel/next.js/tree/canary/examples/cms-builder-io) ([Demo](https://cms-builder-io.vercel.app/)) - [ButterCMS Example](https://github.com/vercel/next.js/tree/canary/examples/cms-buttercms) ([Demo](https://next-blog-buttercms.vercel.app/)) - [Contentful Example](https://github.com/vercel/next.js/tree/canary/examples/cms-contentful) ([Demo](https://app-router-contentful.vercel.app/)) - [Cosmic Example](https://github.com/vercel/next.js/tree/canary/examples/cms-cosmic) ([Demo](https://next-blog-cosmic.vercel.app/)) - [DatoCMS Example](https://github.com/vercel/next.js/tree/canary/examples/cms-datocms) ([Demo](https://next-blog-datocms.vercel.app/)) - [DotCMS Example](https://github.com/vercel/next.js/tree/canary/examples/cms-dotcms) ([Demo](https://nextjs-dotcms-blog.vercel.app/)) - [Drupal Example](https://github.com/vercel/next.js/tree/canary/examples/cms-drupal) ([Demo](https://cms-drupal.vercel.app/)) - [Enterspeed Example](https://github.com/vercel/next.js/tree/canary/examples/cms-enterspeed) ([Demo](https://next-blog-demo.enterspeed.com/)) - [GraphCMS Example](https://github.com/vercel/next.js/tree/canary/examples/cms-graphcms) ([Demo](https://next-blog-graphcms.vercel.app/)) - [Keystone Example](https://github.com/vercel/next.js/tree/canary/examples/cms-keystonejs-embedded) ([Demo](https://nextjs-keystone-demo.vercel.app/)) - [Kontent.ai Example](https://github.com/vercel/next.js/tree/canary/examples/cms-kontent-ai) ([Demo](https://next-blog-kontent-ai.vercel.app/)) - [Makeswift Example](https://github.com/vercel/next.js/tree/canary/examples/cms-makeswift) ([Demo](https://nextjs-makeswift-example.vercel.app/)) - [Plasmic Example](https://github.com/vercel/next.js/tree/canary/examples/cms-plasmic) ([Demo](https://nextjs-plasmic-example.vercel.app/)) - [Prepr Example](https://github.com/vercel/next.js/tree/canary/examples/cms-prepr) ([Demo](https://next-blog-prepr.vercel.app/)) - [Prismic Example](https://github.com/vercel/next.js/tree/canary/examples/cms-prismic) ([Demo](https://next-blog-prismic.vercel.app/)) - [Sanity Example](https://github.com/vercel/next.js/tree/canary/examples/cms-sanity) ([Demo](https://next-blog.sanity.build/)) - [Sitecore XM Cloud Example](https://github.com/vercel/next.js/tree/canary/examples/cms-sitecore-xmcloud) ([Demo](https://vercel-sitecore-xmcloud-demo.vercel.app/)) - [Storyblok Example](https://github.com/vercel/next.js/tree/canary/examples/cms-storyblok) ([Demo](https://next-blog-storyblok.vercel.app/)) - [Strapi Example](https://github.com/vercel/next.js/tree/canary/examples/cms-strapi) ([Demo](https://next-blog-strapi.vercel.app/)) - [TakeShape Example](https://github.com/vercel/next.js/tree/canary/examples/cms-takeshape) ([Demo](https://next-blog-takeshape.vercel.app/)) - [Tina Example](https://github.com/vercel/next.js/tree/canary/examples/cms-tina) ([Demo](https://cms-tina-example.vercel.app/)) - [Umbraco Example](https://github.com/vercel/next.js/tree/canary/examples/cms-umbraco) ([Demo](https://nextjs-umbraco-sample-blog.vercel.app/)) - [Umbraco Heartcore Example](https://github.com/vercel/next.js/tree/canary/examples/cms-umbraco-heartcore) ([Demo](https://next-blog-umbraco-heartcore.vercel.app/)) - [Webiny Example](https://github.com/vercel/next.js/tree/canary/examples/cms-webiny) ([Demo](https://webiny-headlesscms-nextjs-example.vercel.app/)) - [WordPress Example](https://github.com/vercel/next.js/tree/canary/examples/cms-wordpress) ([Demo](https://next-blog-wordpress.vercel.app/)) - [Blog Starter Example](https://github.com/vercel/next.js/tree/canary/examples/blog-starter) ([Demo](https://next-blog-starter.vercel.app/)) - [Static Tweet (Demo)](https://react-tweet.vercel.app/) --- ### 02 Pages 03 Building Your Application 06 Configuring Index (`docs/02-pages/03-building-your-application/06-configuring/index.mdx`) --- title: Configuring description: Learn how to configure your Next.js application. --- Next.js allows you to customize your project to meet specific requirements. This includes integrations with TypeScript, ESlint, and more, as well as internal configuration options such as Absolute Imports and Environment Variables. --- ### 02 Pages 04 Api Reference 01 Components Index (`docs/02-pages/04-api-reference/01-components/index.mdx`) --- title: Components description: API Reference for Next.js built-in components in the Pages Router. source: app/api-reference/components --- {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} --- ### 02 Pages 04 Api Reference 02 File Conventions Index (`docs/02-pages/04-api-reference/02-file-conventions/index.mdx`) --- title: File-system conventions description: API Reference for Next.js file-system conventions. --- --- ### 02 Pages 04 Api Reference 03 Functions Index (`docs/02-pages/04-api-reference/03-functions/index.mdx`) --- title: Functions description: API Reference for Functions and Hooks in Pages Router. source: app/api-reference/functions --- {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} --- ### 02 Pages 04 Api Reference 04 Config Index (`docs/02-pages/04-api-reference/04-config/index.mdx`) --- title: Configuration description: Learn how to configure your Next.js application. --- --- ### 02 Pages 04 Api Reference 05 Cli Index (`docs/02-pages/04-api-reference/05-cli/index.mdx`) --- title: CLI description: API Reference for the Next.js Command Line Interface (CLI) tools. source: app/api-reference/cli --- {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} --- ### 02 Pages 04 Api Reference 06 Adapters Index (`docs/02-pages/04-api-reference/06-adapters/index.mdx`) --- title: Adapters description: Build deployment adapters for Next.js platforms and infrastructure. source: app/api-reference/adapters --- {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the Content component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} --- ### 01 App 03 Api Reference 03 File Conventions 01 Metadata Index (`docs/01-app/03-api-reference/03-file-conventions/01-metadata/index.mdx`) --- title: Metadata Files API Reference nav_title: Metadata Files description: API documentation for the metadata file conventions. --- This section of the docs covers **Metadata file conventions**. File-based metadata can be defined by adding special metadata files to route segments. Each file convention can be defined using a static file (e.g. `opengraph-image.jpg`), or a dynamic variant that uses code to generate the file (e.g. `opengraph-image.js`). Once a file is defined, Next.js will automatically serve the file (with hashes in production for caching) and update the relevant head elements with the correct metadata, such as the asset's URL, file type, and image size. > **Good to know**: > > - Special Route Handlers like [`sitemap.ts`](/docs/app/api-reference/file-conventions/metadata/sitemap), [`opengraph-image.tsx`](/docs/app/api-reference/file-conventions/metadata/opengraph-image), and [`icon.tsx`](/docs/app/api-reference/file-conventions/metadata/app-icons), and other [metadata files](/docs/app/api-reference/file-conventions/metadata) are cached by default. > - If using along with [`proxy.ts`](/docs/app/api-reference/file-conventions/proxy), [configure the matcher](/docs/app/api-reference/file-conventions/proxy#matcher) to exclude the metadata files. --- ### 01 App 03 Api Reference 03 File Conventions 02 Route Segment Config Index (`docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/index.mdx`) --- title: Route Segment Config description: Learn about how to configure options for Next.js route segments. --- The Route Segment Config options allow you to configure the behavior of a [Page](/docs/app/api-reference/file-conventions/page), [Layout](/docs/app/api-reference/file-conventions/layout), or [Route Handler](/docs/app/api-reference/file-conventions/route) by directly exporting the following variables: | Option | Type | Default | | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------- | | [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) | `boolean` | `true` | | [`runtime`](/docs/app/api-reference/file-conventions/route-segment-config/runtime) | `'nodejs' \| 'edge' (deprecated)` | `'nodejs'` | | [`preferredRegion`](/docs/app/api-reference/file-conventions/route-segment-config/preferredRegion) | `'auto' \| 'global' \| 'home' \| string \| string[] (deprecated)` | `'auto'` | | [`maxDuration`](/docs/app/api-reference/file-conventions/route-segment-config/maxDuration) | `number` | Set by deployment platform | With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, pages and layouts also support the following option: | Option | Type | Default | | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------- | | [`ensureStatic`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic) | `'auto'` \| `'shell'` \| `'prefetch'` \| `'navigation'` \| `false` | `'auto'` | ## Version History | Version | | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `v16.0.0` | `dynamic`, `dynamicParams`, `revalidate`, and `fetchCache` removed when [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled. See [Caching and Revalidating (Previous Model)](/docs/app/guides/caching-without-cache-components#route-segment-config). | | `v16.0.0` | `export const experimental_ppr = true` removed. A [codemod](/docs/app/guides/upgrading/codemods#remove-experimental_ppr-route-segment-config-from-app-router-pages-and-layouts) is available. | | `v15.0.0-RC` | `export const runtime = "experimental-edge"` deprecated. A [codemod](/docs/app/guides/upgrading/codemods#transform-app-router-route-segment-config-runtime-value-from-experimental-edge-to-edge) is available. | --- ### 01 App 03 Api Reference 05 Config 01 Next Config Js Index (`docs/01-app/03-api-reference/05-config/01-next-config-js/index.mdx`) --- title: next.config.js description: Learn how to configure your application with next.config.js. --- {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} Next.js can be configured through a `next.config.js` file in the root of your project directory (for example, by `package.json`) with a default export. ```js filename="next.config.js" // @ts-check /** @type {import('next').NextConfig} */ const nextConfig = { /* config options here */ } module.exports = nextConfig ``` ## ECMAScript Modules `next.config.js` is a regular Node.js module, not a JSON file. It gets used by the Next.js server and build phases, and it's not included in the browser build. If you need [ECMAScript modules](https://nodejs.org/api/esm.html), you can use `next.config.mjs`: ```js filename="next.config.mjs" // @ts-check /** * @type {import('next').NextConfig} */ const nextConfig = { /* config options here */ } export default nextConfig ``` > **Good to know**: `next.config` with the `.cjs` or `.cts` extensions are currently **not** supported. ## Configuration as a Function You can also use a function: ```js filename="next.config.mjs" // @ts-check export default (phase, { defaultConfig }) => { /** * @type {import('next').NextConfig} */ const nextConfig = { /* config options here */ } return nextConfig } ``` ### Async Configuration Since Next.js 12.1.0, you can use an async function: ```js filename="next.config.js" // @ts-check module.exports = async (phase, { defaultConfig }) => { /** * @type {import('next').NextConfig} */ const nextConfig = { /* config options here */ } return nextConfig } ``` ### Phase `phase` is the current context in which the configuration is loaded. You can see the [available phases](https://github.com/vercel/next.js/blob/5e6b008b561caf2710ab7be63320a3d549474a5b/packages/next/shared/lib/constants.ts#L19-L23). Phases can be imported from `next/constants`: ```js filename="next.config.js" // @ts-check const { PHASE_DEVELOPMENT_SERVER } = require('next/constants') module.exports = (phase, { defaultConfig }) => { if (phase === PHASE_DEVELOPMENT_SERVER) { return { /* development only config options here */ } } return { /* config options for all phases except development here */ } } ``` ## TypeScript If you are using TypeScript in your project, you can use `next.config.ts` to use TypeScript in your configuration: ```ts filename="next.config.ts" import type { NextConfig } from 'next' const nextConfig: NextConfig = { /* config options here */ } export default nextConfig ``` The commented lines are the place where you can put the configs allowed by `next.config.js`, which are [defined in this file](https://github.com/vercel/next.js/blob/canary/packages/next/src/server/config-shared.ts). However, none of the configs are required, and it's not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do. > Avoid using new JavaScript features not available in your target Node.js version. `next.config.js` will not be parsed by Webpack or Babel. This page documents all the available configuration options: ## Unit Testing (experimental) Starting in Next.js 15.1, the `next/experimental/testing/server` package contains utilities to help unit test `next.config.js` files. The `unstable_getResponseFromNextConfig` function runs the [`headers`](/docs/app/api-reference/config/next-config-js/headers), [`redirects`](/docs/app/api-reference/config/next-config-js/redirects), and [`rewrites`](/docs/app/api-reference/config/next-config-js/rewrites) functions from `next.config.js` with the provided request information and returns `NextResponse` with the results of the routing. > The response from `unstable_getResponseFromNextConfig` only considers `next.config.js` fields and does not consider proxy or filesystem routes, so the result in production may be different than the unit test. ```js import { getRedirectUrl, unstable_getResponseFromNextConfig, } from 'next/experimental/testing/server' const response = await unstable_getResponseFromNextConfig({ url: 'https://nextjs.org/test', nextConfig: { async redirects() { return [{ source: '/test', destination: '/test2', permanent: false }] }, }, }) expect(response.status).toEqual(307) expect(getRedirectUrl(response)).toEqual('https://nextjs.org/test2') ``` --- ### 02 Pages 04 Api Reference 04 Config 01 Next Config Js Index (`docs/02-pages/04-api-reference/04-config/01-next-config-js/index.mdx`) --- title: next.config.js Options description: Learn about the options available in next.config.js for the Pages Router. source: app/api-reference/config/next-config-js --- {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} --- ### Contributing Docs Adding Documentation (`contributing/docs/adding-documentation.md`) # Contributing to Documentation See the [Docs Contribution Guide](https://nextjs.org/docs/community/contribution-guide) to learn how to contribute to the Next.js Documentation. --- ### 01 App 04 Glossary (`docs/01-app/04-glossary.mdx`) --- title: Next.js Glossary nav_title: Glossary description: A glossary of common terms used in Next.js. --- This glossary defines common terms used throughout the Next.js documentation, including terms related to routing, rendering, and caching. # A ## App Router The Next.js router introduced in version 13, built on top of React Server Components. It uses file-system based routing and supports layouts, nested routing, loading states, error handling, and more. Learn more in the [App Router documentation](/docs/app). ## App Shell A per-route prerender containing the parts of a page that don't depend on URL data. Cached content is included when its [`stale`](/docs/app/api-reference/functions/cacheLife#stale) time is at least 5 minutes, since the shell is reused for longer than shorter-lived content stays fresh. Routes that read `cookies()` or `headers()` produce one that also includes session data, cached per session on the client. Used as the default prefetch payload during client navigations, the loading state when a [per-link prefetch](/docs/app/guides/optimizing-prefetching) is not ready, and the fallback for [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components). # B ## Build time The stage when your application is being compiled. During build time, Next.js transforms your code into optimized files for production, generates static pages, and prepares assets for deployment. See the [`next build` CLI reference](/docs/app/api-reference/cli/next#next-build-options). # C ## Cache Components A feature that enables component and function-level caching using the [`"use cache"` directive](/docs/app/api-reference/directives/use-cache). Cache Components allows you to mix static, cached, and dynamic content within a single route by prerendering a static HTML shell that's served immediately, while dynamic content streams in when ready. Configure cache duration with [`cacheLife()`](/docs/app/api-reference/functions/cacheLife), tag cached data with [`cacheTag()`](/docs/app/api-reference/functions/cacheTag), and invalidate on-demand with [`updateTag()`](/docs/app/api-reference/functions/updateTag). Learn more in the [Cache Components guide](/docs/app/getting-started/caching). ## Catch-all Segments Dynamic route segments that can match multiple URL parts using the `[...folder]/page.js` syntax. These segments capture all remaining URL segments and are useful for implementing features like documentation sites or file browsers. Learn more in [Dynamic Route Segments](/docs/app/api-reference/file-conventions/dynamic-routes#catch-all-segments). ## Client Bundles JavaScript bundles sent to the browser. Next.js splits these automatically based on the [module graph](#module-graph) to reduce initial payload size and load only the necessary code for each page. ## Client Component A React component that runs in the browser. In Next.js, Client Components can also be rendered on the server during initial page generation. They can use state, effects, event handlers, and browser APIs, and are marked with the [`"use client"` directive](#use-client-directive) at the top of a file. Learn more in [Server and Client Components](/docs/app/getting-started/server-and-client-components). ## Client-side navigation A navigation technique where the page content updates dynamically without a full page reload. Next.js uses client-side navigation with the [`` component](/docs/app/api-reference/components/link), keeping shared layouts interactive and preserving browser state. Learn more in [Linking and Navigating](/docs/app/getting-started/linking-and-navigating#client-side-transitions). ## Client Cache An in-memory cache in the browser that stores [RSC Payload](#rsc-payload) for visited and prefetched routes. During [client-side navigation](#client-side-navigation), Next.js serves cached [layouts](#layout) and [loading states](#loading-ui) instantly without a server request. Pages are not cached by default but are reused during browser back/forward navigation. The client cache is cleared on page refresh. It can be invalidated programmatically with [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag), [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath), [`updateTag`](/docs/app/api-reference/functions/updateTag), [`router.refresh`](/docs/app/api-reference/functions/use-router), [`cookies.set`](/docs/app/api-reference/functions/cookies), or [`cookies.delete`](/docs/app/api-reference/functions/cookies). You can configure the client cache duration with [`staleTimes`](/docs/app/api-reference/config/next-config-js/staleTimes) globally, or per-route via the `stale` property in [`cacheLife`](/docs/app/api-reference/functions/cacheLife#client-cache-behavior) (recommended). ## Code Splitting The process of dividing your application into smaller JavaScript chunks based on routes. Instead of loading all code upfront, only the code needed for the current route is loaded, reducing initial load time. Next.js automatically performs code splitting based on routes. Learn more in the [Package Bundling guide](/docs/app/guides/package-bundling). # D ## Dynamic rendering When a component is rendered at request time rather than [build time](#build-time). A component becomes dynamic when it uses [Request-time APIs](#request-time-apis). ## Dynamic route segments [Route segments](#route-segment) that are generated from data at request time. Created by wrapping a folder name in square brackets (e.g., `[slug]`), they allow you to create routes from dynamic data like blog posts or product pages. Learn more in [Dynamic Route Segments](/docs/app/api-reference/file-conventions/dynamic-routes). # E ## Environment Variables Configuration values accessible at build time or request time. In Next.js, variables prefixed with `NEXT_PUBLIC_` are exposed to the browser, while others are only available server-side. Learn more in [Environment Variables](/docs/app/guides/environment-variables). ## Error Boundary A React component that catches JavaScript errors in its child component tree and displays a fallback UI. In Next.js, create an [`error.js` file](/docs/app/api-reference/file-conventions/error) to automatically wrap a route segment in an error boundary. Learn more in [Error Handling](/docs/app/getting-started/error-handling). # F ## Font Optimization Automatic font optimization using [`next/font`](/docs/app/api-reference/components/font). Next.js self-hosts fonts, eliminates layout shift, and applies best practices for performance. Works with Google Fonts and local font files. Learn more in [Fonts](/docs/app/getting-started/fonts). ## File-system caching A Turbopack feature that stores compiler artifacts on disk between runs, reducing work across `next dev` or `next build` commands for significantly faster compile times. Learn more in [Turbopack FileSystem Caching](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache). # H ## Hydration React's process of attaching event handlers to the DOM to make server-rendered static HTML interactive. During hydration, React reconciles the server-rendered markup with the client-side JavaScript. Learn more in [Server and Client Components](/docs/app/getting-started/server-and-client-components#how-do-server-and-client-components-work-in-nextjs). # I ## Import Aliases Custom path mappings that provide shorthand references for frequently used directories. Import aliases reduce the complexity of relative imports and make code more readable and maintainable. Learn more in [Absolute Imports and Module Path Aliases](/docs/app/getting-started/installation#set-up-absolute-imports-and-module-path-aliases). ## Incremental Static Regeneration (ISR) A technique that allows you to update static content without rebuilding the entire site. ISR enables you to use static generation on a per-page basis while revalidating pages in the background as traffic comes in. Learn more in the [ISR guide](/docs/app/guides/incremental-static-regeneration) or, when using Cache Components, [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components). > **Good to know**: In Next.js, ISR is also known as [Revalidation](#revalidation). ## Intercepting Routes A routing pattern that allows loading a route from another part of your application within the current layout. Useful for displaying content (like modals) without the user switching context, while keeping the URL shareable. Learn more in [Intercepting Routes](/docs/app/api-reference/file-conventions/intercepting-routes). ## Image Optimization Automatic image optimization using the [`` component](/docs/app/api-reference/components/image). Next.js optimizes images on-demand, serves them in modern formats like WebP, and automatically handles lazy loading and responsive sizing. Learn more in [Images](/docs/app/getting-started/images). # L ## Layout UI that is shared between multiple pages. Layouts preserve state, remain interactive, and do not re-render on navigation. Defined by exporting a React component from a [`layout.js` file](/docs/app/api-reference/file-conventions/layout). Learn more in [Layouts and Pages](/docs/app/getting-started/layouts-and-pages). ## Loading UI Fallback UI shown while a [route segment](#route-segment) is loading. Created by adding a [`loading.js` file](/docs/app/api-reference/file-conventions/loading) to a folder, which automatically wraps the page in a [Suspense boundary](#suspense-boundary). Learn more in [Loading UI](/docs/app/api-reference/file-conventions/loading). # M ## Module Graph A graph of file dependencies in your app. Each file (module) is a node, and import/export relationships form the edges. Next.js analyzes this graph to determine optimal bundling and code-splitting strategies. Learn more in [Server and Client Components](/docs/app/getting-started/server-and-client-components#reducing-js-bundle-size). ## Metadata Information about a page used by browsers and search engines, such as title, description, and Open Graph images. In Next.js, define metadata using the [`metadata` export](/docs/app/api-reference/functions/generate-metadata) or [`generateMetadata` function](/docs/app/api-reference/functions/generate-metadata) in layout or page files. Learn more in [Metadata and OG Images](/docs/app/getting-started/metadata-and-og-images). ## Memoization Caching the return value of a function so that calling the same function multiple times during a render pass (request) only executes it once. In Next.js, `fetch` `GET` requests with the same URL and options are automatically memoized across Server Components, layouts, pages, and `generateMetadata`/`generateStaticParams` (but not [Route Handlers](/docs/app/api-reference/file-conventions/route) since they are not part of the React component tree). For non-`fetch` operations, use the React [`cache`](https://react.dev/reference/react/cache) function. Learn more in the [`fetch` API reference](/docs/app/api-reference/functions/fetch). ## Middleware See [Proxy](#proxy). # N ## Navigation stages The points at which server-rendered work becomes available during a client navigation. With [Partial Prefetching](#partial-prefetching), the stages are the [App Shell](#app-shell), a per-link prefetch, and the navigation. Learn more in the [`ensureStatic`](/docs/app/api-reference/file-conventions/route-segment-config/ensureStatic), [`prefetch()`](/docs/app/api-reference/functions/prefetch), and [`navigation()`](/docs/app/api-reference/functions/navigation) API references. ## Not Found A special component shown when a route doesn't exist or when the [`notFound()` function](/docs/app/api-reference/functions/not-found) is called. Created by adding a [`not-found.js` file](/docs/app/api-reference/file-conventions/not-found) to your app directory. Learn more in [Error Handling](/docs/app/getting-started/error-handling#not-found). # P ## Private Folders Folders prefixed with an underscore (e.g., `_components`) that are excluded from the routing system. These folders are used for code organization and shared utilities without creating accessible routes. Learn more in [Private Folders](/docs/app/getting-started/project-structure#private-folders). ## Page UI that is unique to a route. Defined by exporting a React component from a [`page.js` file](/docs/app/api-reference/file-conventions/page) within the `app` directory. Learn more in [Layouts and Pages](/docs/app/getting-started/layouts-and-pages). ## Parallel Routes A pattern that allows simultaneously or conditionally rendering multiple pages within the same layout. Created using named slots with the `@folder` convention, useful for dashboards, modals, and complex layouts. Learn more in [Parallel Routes](/docs/app/api-reference/file-conventions/parallel-routes). ## Partial Prefetching A prefetching strategy for [Cache Components](#cache-components) routes where a `` prefetches a per-route [App Shell](#app-shell) by default instead of the full page. Enable it with [`partialPrefetching: true`](/docs/app/api-reference/config/next-config-js/partialPrefetching) in `next.config.ts`. Learn more in the [Adopting Partial Prefetching guide](/docs/app/guides/adopting-partial-prefetching). ## Partial Prerendering (PPR) A rendering optimization that combines prerendering and dynamic rendering in a single route. The static shell is served immediately while dynamic content streams in when ready, providing the best of both rendering strategies. Learn more in [Cache Components](/docs/app/getting-started/caching). ## Prefetching Loading a route in the background before the user navigates to it. Next.js automatically prefetches routes linked with the [`` component](/docs/app/api-reference/components/link) when they enter the viewport, making navigation feel instant. Learn more in the [Prefetching guide](/docs/app/guides/prefetching). ## Prerendering When a component is rendered at [build time](#build-time) or in the background during [revalidation](#revalidation). The result is HTML and [RSC Payload](#rsc-payload), which can be cached and served from a CDN. Prerendering is the default for components that don't use [Request-time APIs](#request-time-apis). ## Proxy A file ([`proxy.js`](/docs/app/api-reference/file-conventions/proxy)) that runs code on the server before request is completed. Used to implement server-side logic like logging, redirects, and rewrites. Formerly known as Middleware. Learn more in the [Proxy guide](/docs/app/getting-started/proxy). # R ## Redirect Sending users from one URL to another. In Next.js, redirects can be configured in [`next.config.js`](/docs/app/api-reference/config/next-config-js/redirects), returned from [Proxy](/docs/app/api-reference/file-conventions/proxy), or triggered programmatically with the [`redirect()` function](/docs/app/api-reference/functions/redirect). Learn more in [Redirecting](/docs/app/guides/redirecting). ## Request-time APIs Functions that access request-specific data, causing a component to opt into [dynamic rendering](#dynamic-rendering). These include: - [`cookies()`](/docs/app/api-reference/functions/cookies) - Access request cookies - [`headers()`](/docs/app/api-reference/functions/headers) - Access request headers - [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) - Access URL query parameters - [`draftMode()`](/docs/app/api-reference/functions/draft-mode) - Enable or check draft mode ## Runtime rendering See [Dynamic rendering](#dynamic-rendering). ## Revalidation The process of updating cached data. Can be time-based (using [`cacheLife()`](/docs/app/api-reference/functions/cacheLife) to set cache duration) or on-demand (using [`cacheTag()`](/docs/app/api-reference/functions/cacheTag) to tag data, then [`updateTag()`](/docs/app/api-reference/functions/updateTag) to invalidate). Learn more in [Caching and Revalidating](/docs/app/getting-started/caching). ## Rewrite Mapping an incoming request path to a different destination path without changing the URL in the browser. Configured in [`next.config.js`](/docs/app/api-reference/config/next-config-js/rewrites) or returned from [Proxy](/docs/app/api-reference/file-conventions/proxy). Useful for proxying to external services or legacy URLs. ## Route Groups A way to organize routes without affecting the URL structure. Created by wrapping a folder name in parentheses (e.g., `(marketing)`), route groups help organize related routes and enable per-group [layouts](#layout). Learn more in [Route Groups](/docs/app/api-reference/file-conventions/route-groups). ## Route Handler A function that handles HTTP requests for a specific route, defined in a [`route.js` file](/docs/app/api-reference/file-conventions/route). Route Handlers use the Web Request and Response APIs and can handle `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, and `OPTIONS` methods. Learn more in [Route Handlers](/docs/app/getting-started/route-handlers). ## Route Segment A part of the URL path (between two slashes) defined by a folder in the `app` directory. Each folder represents a segment in the URL structure. Learn more in [Project Structure](/docs/app/getting-started/project-structure). ## RSC Payload The React Server Component Payload is a compact binary representation of the rendered React Server Components tree. It contains the rendered result of Server Components, placeholders for Client Components, and props passed between them. Learn more in [Server and Client Components](/docs/app/getting-started/server-and-client-components#how-do-server-and-client-components-work-in-nextjs). # S ## Server Component The default component type in the App Router. Server Components render on the server, can fetch data directly, and don't add to the client JavaScript bundle. They cannot use state or browser APIs. Learn more in [Server and Client Components](/docs/app/getting-started/server-and-client-components). ## Server Action A [Server Function](#server-function) that is passed to a Client Component as a prop or bound to a form action. Server Actions are commonly used for form submissions and data mutations. Learn more in [Server Actions and Mutations](/docs/app/guides/server-actions). ## Server Function An asynchronous function that runs on the server, marked with the [`"use server"` directive](/docs/app/api-reference/directives/use-server). Server Functions can be invoked from Client Components. When passed as a prop to a Client Component or bound to a form action, they are called [Server Actions](#server-action). Learn more in [React Server Functions](https://react.dev/reference/rsc/server-functions). ## Static Export A deployment mode that generates a fully static site with HTML, CSS, and JavaScript files. Enabled by setting `output: 'export'` in `next.config.js`. Static exports can be hosted on any static file server without a Node.js server. Learn more in [Static Exports](/docs/app/guides/static-exports). ## Static rendering See [Prerendering](#prerendering). ## Static Assets Files such as images, fonts, videos, and other media that are served directly without processing. Static assets are typically stored in the `public` directory and referenced by their relative paths. Learn more in [Static Assets](/docs/app/api-reference/file-conventions/public-folder). ## Static Shell The prerendered HTML structure of a page that's served immediately to the browser. With [Partial Prerendering](#partial-prerendering-ppr), the static shell includes all statically renderable content plus [Suspense boundary](#suspense-boundary) fallbacks for dynamic content that streams in later. ## Streaming A technique that allows the server to send parts of a page to the client as they become ready, rather than waiting for the entire page to render. Enabled automatically with [`loading.js`](/docs/app/api-reference/file-conventions/loading) or manual `` boundaries. Learn more in the [Streaming guide](/docs/app/guides/streaming). ## Suspense boundary A React [``](https://react.dev/reference/react/Suspense) component that wraps async content and displays fallback UI while it loads. In Next.js, Suspense boundaries define where the [static shell](#static-shell) ends and [streaming](#streaming) begins, enabling [Partial Prerendering](#partial-prerendering-ppr). # T ## Turbopack A fast, Rust-based bundler built for Next.js. Turbopack is the default bundler for `next dev` and available for `next build`. It provides significantly faster compilation times compared to Webpack. Learn more in [Turbopack](/docs/app/api-reference/turbopack). ## Tree Shaking The process of removing unused code from your JavaScript bundles during the build process. Next.js automatically tree-shakes your code to reduce bundle sizes. Learn more in the [Package Bundling guide](/docs/app/guides/package-bundling). # U ## URL data Data that identifies a specific URL, such as the pathname and query parameters. In the App Router this means [`params`](/docs/app/api-reference/file-conventions/page#params-optional) and [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional), and the client hooks that read them like [`usePathname`](/docs/app/api-reference/functions/use-pathname) and [`useSearchParams`](/docs/app/api-reference/functions/use-search-params). URL data varies per link, not per session, so it can't be part of a shared [App Shell](#app-shell). ## `"use cache"` Directive A directive that marks a component or function as cacheable. It can be placed at the top of a file to indicate that all exports in the file are cacheable, or inline at the top of a function or component to mark that specific scope as cacheable. Learn more in the [`"use cache"` reference](/docs/app/api-reference/directives/use-cache). ## `"use client"` Directive A special React directive that marks the boundary between server and client code. It must be placed at the top of a file, before any imports or other code. It indicates that React Components, helper functions, variable declarations, and all imported dependencies should be included in the [client bundle](#client-bundles). Learn more in the [`"use client"` reference](/docs/app/api-reference/directives/use-client). ## `"use server"` Directive A directive that marks a function as a [Server Function](#server-function) that can be called from client-side code. It can be placed at the top of a file to indicate that all exports in the file are Server Functions, or inline at the top of a function to mark that specific function. Learn more in the [`"use server"` reference](/docs/app/api-reference/directives/use-server). # V ## Version skew After a new version of your application is deployed, clients that are still active may reference JavaScript, CSS, or data from an older build. This mismatch between client and server versions is called version skew, and it can cause missing assets, Server Action errors, and navigation failures. Next.js uses [`deploymentId`](/docs/app/api-reference/config/next-config-js/deploymentId) to detect and handle version skew. Learn more in [Self-Hosting - Version Skew](/docs/app/guides/self-hosting#version-skew). --- ### 03 Architecture Accessibility (`docs/03-architecture/accessibility.mdx`) --- title: Accessibility description: The built-in accessibility features of Next.js. --- The Next.js team is committed to making Next.js accessible to all developers (and their end-users). By adding accessibility features to Next.js by default, we aim to make the Web more inclusive for everyone. ## Route Announcements When transitioning between pages rendered on the server (e.g. using the `` tag) screen readers and other assistive technology announce the page title when the page loads so that users understand that the page has changed. In addition to traditional page navigations, Next.js also supports client-side transitions for improved performance (using `next/link`). To ensure that client-side transitions are also announced to assistive technology, Next.js includes a route announcer by default. The Next.js route announcer looks for the page name to announce by first inspecting `document.title`, then the `

` element, and finally the URL pathname. For the most accessible user experience, ensure that each page in your application has a unique and descriptive title. ## Linting Next.js provides an [integrated ESLint experience](/docs/pages/api-reference/config/eslint) out of the box, including custom rules for Next.js. By default, Next.js includes `eslint-plugin-jsx-a11y` to help catch accessibility issues early, including warning on: - [aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/aria-props.md?rgh-link-date=2021-06-04T02%3A10%3A36Z) - [aria-proptypes](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/aria-proptypes.md?rgh-link-date=2021-06-04T02%3A10%3A36Z) - [aria-unsupported-elements](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/aria-unsupported-elements.md?rgh-link-date=2021-06-04T02%3A10%3A36Z) - [role-has-required-aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/role-has-required-aria-props.md?rgh-link-date=2021-06-04T02%3A10%3A36Z) - [role-supports-aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/role-supports-aria-props.md?rgh-link-date=2021-06-04T02%3A10%3A36Z) For example, this plugin helps ensure you add alt text to `img` tags, use correct `aria-*` attributes, use correct `role` attributes, and more. ## Accessibility Resources - [WebAIM WCAG checklist](https://webaim.org/standards/wcag/checklist) - [WCAG 2.2 Guidelines](https://www.w3.org/TR/WCAG22/) - [The A11y Project](https://www.a11yproject.com/) - Check [color contrast ratios](https://developer.mozilla.org/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) between foreground and background elements - Use [`prefers-reduced-motion`](https://web.dev/prefers-reduced-motion/) when working with animations --- ### 03 Architecture Fast Refresh (`docs/03-architecture/fast-refresh.mdx`) --- title: Fast Refresh description: Fast Refresh is a hot module reloading experience that gives you instantaneous feedback on edits made to your React components. --- Fast refresh is a React feature integrated into Next.js that allows you to live reload the browser page while maintaining temporary client-side state when you save changes to a file. It's enabled by default in all Next.js applications on **9.4 or newer**. With Fast Refresh enabled, most edits should be visible within a second. ## How It Works - If you edit a file that **only exports React component(s)**, Fast Refresh will update the code only for that file, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects. - If you edit a file with exports that _aren't_ React components, Fast Refresh will re-run both that file, and the other files importing it. So if both `Button.js` and `Modal.js` import `theme.js`, editing `theme.js` will update both components. - Finally, if you **edit a file** that's **imported by files outside of the React tree**, Fast Refresh **will fall back to doing a full reload**. You might have a file which renders a React component but also exports a value that is imported by a **non-React component**. For example, maybe your component also exports a constant, and a non-React utility file imports it. In that case, consider migrating the constant to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way. ## Error Resilience ### Syntax Errors If you make a syntax error during development, you can fix it and save the file again. The error will disappear automatically, so you won't need to reload the app. **You will not lose component state**. ### Runtime Errors If you make a mistake that leads to a runtime error inside your component, you'll be greeted with a contextual overlay. Fixing the error will automatically dismiss the overlay, without reloading the app. Component state will be retained if the error did not occur during rendering. If the error did occur during rendering, React will remount your application using the updated code. If you have [error boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary) in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a rendering error. This means having an error boundary can prevent you from always getting reset to the root app state. However, keep in mind that error boundaries shouldn't be _too_ granular. They are used by React in production, and should always be designed intentionally. ## Limitations Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file: - Local state is not preserved for class components (only function components and Hooks preserve state). - The file you're editing might have _other_ exports in addition to a React component. - Sometimes, a file would export the result of calling a higher-order component like `HOC(WrappedComponent)`. If the returned component is a class, its state will be reset. - Anonymous arrow functions like `export default () =>
;` cause Fast Refresh to not preserve local component state. For large codebases you can use our [`name-default-component` codemod](/docs/pages/guides/upgrading/codemods#name-default-component). As more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases. ## Tips - Fast Refresh preserves React local state in function components (and Hooks) by default. - Sometimes you might want to _force_ the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add `// @refresh reset` anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit. - You can put `console.log` or `debugger;` into the components you edit during development. - Remember that imports are case sensitive. Both fast and full refresh can fail, when your import doesn't match the actual filename. For example, `'./header'` vs `'./Header'`. ## Fast Refresh and Hooks When possible, Fast Refresh attempts to preserve the state of your component between edits. In particular, `useState` and `useRef` preserve their previous values as long as you don't change their arguments or the order of the Hook calls. Hooks with dependencies—such as `useEffect`, `useMemo`, and `useCallback`—will _always_ update during Fast Refresh. Their list of dependencies will be ignored while Fast Refresh is happening. For example, when you edit `useMemo(() => x * 2, [x])` to `useMemo(() => x * 10, [x])`, it will re-run even though `x` (the dependency) has not changed. If React didn't do that, your edit wouldn't reflect on the screen! Sometimes, this can lead to unexpected results. For example, even a `useEffect` with an empty array of dependencies would still re-run once during Fast Refresh. However, writing code resilient to occasional re-running of `useEffect` is a good practice even without Fast Refresh. It will make it easier for you to introduce new dependencies to it later on and it's enforced by [React Strict Mode](/docs/pages/api-reference/config/next-config-js/reactStrictMode), which we highly recommend enabling. --- ### 03 Architecture Nextjs Compiler (`docs/03-architecture/nextjs-compiler.mdx`) --- title: Next.js Compiler description: Next.js Compiler, written in Rust, which transforms and minifies your Next.js application. --- The Next.js Compiler, written in Rust using [SWC](https://swc.rs/), allows Next.js to transform and minify your JavaScript code for production. This replaces Babel for individual files and Terser for minifying output bundles. Compilation using the Next.js Compiler is 17x faster than Babel and enabled by default since Next.js version 12. If you have an existing Babel configuration or are using [unsupported features](#unsupported-features), your application will opt-out of the Next.js Compiler and continue using Babel. ## Why SWC? [SWC](https://swc.rs/) is an extensible Rust-based platform for the next generation of fast developer tools. SWC can be used for compilation, minification, bundling, and more – and is designed to be extended. It's something you can call to perform code transformations (either built-in or custom). Running those transformations happens through higher-level tools like Next.js. We chose to build on SWC for a few reasons: - **Extensibility:** SWC can be used as a Crate inside Next.js, without having to fork the library or workaround design constraints. - **Performance:** We were able to achieve ~3x faster Fast Refresh and ~5x faster builds in Next.js by switching to SWC, with more room for optimization still in progress. - **WebAssembly:** Rust's support for WASM is essential for supporting all possible platforms and taking Next.js development everywhere. - **Community:** The Rust community and ecosystem are amazing and still growing. ## Supported Features ### Styled Components We're working to port `babel-plugin-styled-components` to the Next.js Compiler. First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `next.config.js` file: ```js filename="next.config.js" module.exports = { compiler: { styledComponents: true, }, } ``` For advanced use cases, you can configure individual properties for styled-components compilation. > Note: `ssr` and `displayName` transforms are the main requirement for using `styled-components` in Next.js. ```js filename="next.config.js" module.exports = { compiler: { // see https://styled-components.com/docs/tooling#babel-plugin for more info on the options. styledComponents: { // Enabled by default in development, disabled in production to reduce file size, // setting this will override the default for all environments. displayName?: boolean, // Enabled by default. ssr?: boolean, // Enabled by default. fileName?: boolean, // Empty by default. topLevelImportPaths?: string[], // Defaults to ["index"]. meaninglessFileNames?: string[], // Enabled by default. minify?: boolean, // Enabled by default. transpileTemplateLiterals?: boolean, // Empty by default. namespace?: string, // Disabled by default. pure?: boolean, // Enabled by default. cssProp?: boolean, }, }, } ``` ### Jest The Next.js Compiler transpiles your tests and simplifies configuring Jest together with Next.js including: - Auto mocking of `.css`, `.module.css` (and their `.scss` variants), and image imports - Automatically sets up `transform` using SWC - Loading `.env` (and all variants) into `process.env` - Ignores `node_modules` from test resolving and transforms - Ignoring `.next` from test resolving - Loads `next.config.js` for flags that enable experimental SWC transforms First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jest.config.js` file: ```js filename="jest.config.js" const nextJest = require('next/jest') // Providing the path to your Next.js app which will enable loading next.config.js and .env files const createJestConfig = nextJest({ dir: './' }) // Any custom config you want to pass to Jest const customJestConfig = { setupFilesAfterEnv: ['/jest.setup.js'], } // createJestConfig is exported in this way to ensure that next/jest can load the Next.js configuration, which is async module.exports = createJestConfig(customJestConfig) ``` ### Relay To enable [Relay](https://relay.dev/) support: ```js filename="next.config.js" module.exports = { compiler: { relay: { // This should match relay.config.js src: './', artifactDirectory: './__generated__', language: 'typescript', eagerEsModules: false, }, }, } ``` > **Good to know**: In Next.js, all JavaScript files in `pages` directory are considered routes. So, for `relay-compiler` you'll need to specify `artifactDirectory` configuration settings outside of the `pages`, otherwise `relay-compiler` will generate files next to the source file in the `__generated__` directory, and this file will be considered a route, which will break production builds. ### Remove React Properties Allows to remove JSX properties. This is often used for testing. Similar to `babel-plugin-react-remove-properties`. To remove properties matching the default regex `^data-test`: ```js filename="next.config.js" module.exports = { compiler: { reactRemoveProperties: true, }, } ``` To remove custom properties: ```js filename="next.config.js" module.exports = { compiler: { // The regexes defined here are processed in Rust so the syntax is different from // JavaScript `RegExp`s. See https://docs.rs/regex. reactRemoveProperties: { properties: ['^data-custom$'] }, }, } ``` ### Remove Console This transform allows for removing all `console.*` calls in application code (not `node_modules`). Similar to `babel-plugin-transform-remove-console`. Remove all `console.*` calls: ```js filename="next.config.js" module.exports = { compiler: { removeConsole: true, }, } ``` Remove `console.*` output except `console.error`: ```js filename="next.config.js" module.exports = { compiler: { removeConsole: { exclude: ['error'], }, }, } ``` ### Legacy Decorators Next.js will automatically detect `experimentalDecorators` in `jsconfig.json` or `tsconfig.json`. Legacy decorators are commonly used with older versions of libraries like `mobx`. This flag is only supported for compatibility with existing applications. We do not recommend using legacy decorators in new applications. First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jsconfig.json` or `tsconfig.json` file: ```js { "compilerOptions": { "experimentalDecorators": true } } ``` ### importSource Next.js will automatically detect `jsxImportSource` in `jsconfig.json` or `tsconfig.json` and apply that. This is commonly used with libraries like [Theme UI](https://theme-ui.com). First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `jsconfig.json` or `tsconfig.json` file: ```js { "compilerOptions": { "jsxImportSource": "theme-ui" } } ``` ### Emotion We're working to port `@emotion/babel-plugin` to the Next.js Compiler. First, update to the latest version of Next.js: `npm install next@latest`. Then, update your `next.config.js` file: ```js filename="next.config.js" module.exports = { compiler: { emotion: boolean | { // default is true. It will be disabled when build type is production. sourceMap?: boolean, // default is 'dev-only'. autoLabel?: 'never' | 'dev-only' | 'always', // default is '[local]'. // Allowed values: `[local]` `[filename]` and `[dirname]` // This option only works when autoLabel is set to 'dev-only' or 'always'. // It allows you to define the format of the resulting label. // The format is defined via string where variable parts are enclosed in square brackets []. // For example labelFormat: "my-classname--[local]", where [local] will be replaced with the name of the variable the result is assigned to. labelFormat?: string, // default is undefined. // This option allows you to tell the compiler what imports it should // look at to determine what it should transform so if you re-export // Emotion's exports, you can still use transforms. importMap?: { [packageName: string]: { [exportName: string]: { canonicalImport?: [string, string], styledBaseImport?: [string, string], } } }, }, }, } ``` ### Minification Next.js' swc compiler is used for minification by default since v13. This is 7x faster than Terser. > **Good to know:** Starting with v15, minification cannot be customized using `next.config.js`. Support for the `swcMinify` flag has been removed. ### Module Transpilation Next.js can automatically transpile and bundle dependencies from local packages (like monorepos) or from external dependencies (`node_modules`). This replaces the `next-transpile-modules` package. ```js filename="next.config.js" module.exports = { transpilePackages: ['@acme/ui', 'lodash-es'], } ``` ### Modularize Imports This option has been superseded by [`optimizePackageImports`](/docs/app/api-reference/config/next-config-js/optimizePackageImports) in Next.js 13.5. We recommend upgrading to use the new option that does not require manual configuration of import paths. ### Define (Replacing variables during build) The `define` option allows you to statically replace variables in your code at build-time. The option takes an object as key-value pairs, where the keys are the variables that should be replaced with the corresponding values. Use the `compiler.define` field in `next.config.js` to define variables for all environments (server, edge, and client). Or, use `compiler.defineServer` to define variables only for server-side (server and edge) code: ```js filename="next.config.js" module.exports = { compiler: { define: { MY_VARIABLE: 'my-string', 'process.env.MY_ENV_VAR': 'my-env-var', }, defineServer: { MY_SERVER_VARIABLE: 'my-server-var', }, }, } ``` ### Build Lifecycle Hooks The Next.js Compiler supports lifecycle hooks that allow you to run custom code at specific points during the build process. Currently, the following hook is supported: #### runAfterProductionCompile A hook function that executes after production build compilation finishes, but before running post-compilation tasks such as type checking and static page generation. This hook provides access to project metadata including the project directory and build output directory, making it useful for third-party tools to collect build outputs like sourcemaps. ```js filename="next.config.js" module.exports = { compiler: { runAfterProductionCompile: async ({ distDir, projectDir }) => { // Your custom code here }, }, } ``` The hook receives an object with the following properties: - `distDir`: The build output directory (defaults to `.next`) - `projectDir`: The root directory of the project ## Experimental Features ### SWC Trace profiling You can generate SWC's internal transform traces as chromium's [trace event format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview?mode=html#%21=). ```js filename="next.config.js" module.exports = { experimental: { swcTraceProfiling: true, }, } ``` Once enabled, swc will generate trace named as `swc-trace-profile-${timestamp}.json` under `.next/`. Chromium's trace viewer (chrome://tracing/, https://ui.perfetto.dev/), or compatible flamegraph viewer (https://www.speedscope.app/) can load & visualize generated traces. ### SWC Plugins (experimental) You can configure swc's transform to use SWC's experimental plugin support written in wasm to customize transformation behavior. ```js filename="next.config.js" module.exports = { experimental: { swcPlugins: [ [ 'plugin', { ...pluginOptions, }, ], ], }, } ``` `swcPlugins` accepts an array of tuples for configuring plugins. A tuple for the plugin contains the path to the plugin and an object for plugin configuration. The path to the plugin can be an npm module package name or an absolute path to the `.wasm` binary itself. ## Unsupported Features When your application has a `.babelrc` file, Next.js will automatically fall back to using Babel for transforming individual files. This ensures backwards compatibility with existing applications that leverage custom Babel plugins. If you're using a custom Babel setup, [please share your configuration](https://github.com/vercel/next.js/discussions/30174). We're working to port as many commonly used Babel transformations as possible, as well as supporting plugins in the future. ## Version History | Version | Changes | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `v13.1.0` | [Module Transpilation](https://nextjs.org/blog/next-13-1#built-in-module-transpilation-stable) and [Modularize Imports](https://nextjs.org/blog/next-13-1#import-resolution-for-smaller-bundles) stable. | | `v13.0.0` | SWC Minifier enabled by default. | | `v12.3.0` | SWC Minifier [stable](https://nextjs.org/blog/next-12-3#swc-minifier-stable). | | `v12.2.0` | [SWC Plugins](#swc-plugins-experimental) experimental support added. | | `v12.1.0` | Added support for Styled Components, Jest, Relay, Remove React Properties, Legacy Decorators, Remove Console, and jsxImportSource. | | `v12.0.0` | Next.js Compiler [introduced](https://nextjs.org/blog/next-12). | --- ### 03 Architecture Supported Browsers (`docs/03-architecture/supported-browsers.mdx`) --- title: Supported Browsers description: Browser support and which JavaScript features are supported by Next.js. --- Next.js supports **modern browsers** with zero configuration. - Chrome 111+ - Edge 111+ - Firefox 111+ - Safari 16.4+ ## Browserslist If you would like to target specific browsers or features, Next.js supports [Browserslist](https://browsersl.ist) configuration in your `package.json` file. Next.js uses the following Browserslist configuration by default: ```json filename="package.json" { "browserslist": ["chrome 111", "edge 111", "firefox 111", "safari 16.4"] } ``` ## Polyfills We inject [widely used polyfills](https://github.com/vercel/next.js/blob/canary/packages/next-polyfill-nomodule/src/index.js), including: - [**fetch()**](https://developer.mozilla.org/docs/Web/API/Fetch_API) — Replacing: `whatwg-fetch` and `unfetch`. - [**URL**](https://developer.mozilla.org/docs/Web/API/URL) — Replacing: the [`url` package (Node.js API)](https://nodejs.org/api/url.html). - [**Object.assign()**](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) — Replacing: `object-assign`, `object.assign`, and `core-js/object/assign`. If any of your dependencies include these polyfills, they’ll be eliminated automatically from the production build to avoid duplication. In addition, to reduce bundle size, Next.js will only load these polyfills for browsers that require them. The majority of the web traffic globally will not download these polyfills. ### Custom Polyfills If your own code or any external npm dependencies require features not supported by your target browsers (such as IE 11), you need to add polyfills yourself. #### In App Router To include polyfills, you can import them into the [`instrumentation-client.js` file](/docs/app/api-reference/file-conventions/instrumentation-client). ```ts filename="instrumentation-client.ts" import './polyfills' ``` #### In Pages Router In this case, you should add a top-level import for the **specific polyfill** you need in your [Custom ``](/docs/pages/building-your-application/routing/custom-app) or the individual component. ```tsx filename="pages/_app.tsx" switcher import './polyfills' import type { AppProps } from 'next/app' export default function MyApp({ Component, pageProps }: AppProps) { return } ``` ```jsx filename="pages/_app.jsx" switcher import './polyfills' export default function MyApp({ Component, pageProps }) { return } ``` #### Conditionally loading polyfills The best approach is to isolate unsupported features to specific UI sections and conditionally load the polyfill if needed. ```ts filename="hooks/analytics.ts" switcher import { useCallback } from 'react' export const useAnalytics = () => { const tracker = useCallback(async (data: unknown) => { if (!('structuredClone' in globalThis)) { const mod = await import('polyfills/structured-clone') globalThis.structuredClone = mod.default } /* Do some work that uses structured clone */ }, []) return tracker } ``` ```js filename="hooks/analytics.js" switcher import { useCallback } from 'react' export const useAnalytics = () => { const tracker = useCallback(async (data) => { if (!('structuredClone' in globalThis)) { const mod = await import('polyfills/structured-clone') globalThis.structuredClone = mod.default } /* Do some work that uses structured clone */ }, []) return tracker } ``` ## JavaScript Language Features Next.js allows you to use the latest JavaScript features out of the box. In addition to [ES6 features](https://github.com/lukehoban/es6features), Next.js also supports: - [Async/await](https://github.com/tc39/ecmascript-asyncawait) (ES2017) - [Object Rest/Spread Properties](https://github.com/tc39/proposal-object-rest-spread) (ES2018) - [Dynamic `import()`](https://github.com/tc39/proposal-dynamic-import) (ES2020) - [Optional Chaining](https://github.com/tc39/proposal-optional-chaining) (ES2020) - [Nullish Coalescing](https://github.com/tc39/proposal-nullish-coalescing) (ES2020) - [Class Fields](https://github.com/tc39/proposal-class-fields) and [Static Properties](https://github.com/tc39/proposal-static-class-features) (ES2022) - and more! ### TypeScript Features Next.js has built-in TypeScript support. [Learn more here](/docs/pages/api-reference/config/typescript). ### Customizing Babel Config (Advanced) You can customize babel configuration. [Learn more here](/docs/pages/guides/babel). --- ### 04 Community 01 Contribution Guide (`docs/04-community/01-contribution-guide.mdx`) --- title: Docs Contribution Guide nav_title: Contribution Guide description: Learn how to contribute to Next.js Documentation --- Welcome to the Next.js Docs Contribution Guide! We're excited to have you here. This page provides instructions on how to edit the Next.js documentation. Our goal is to ensure that everyone in the community feels empowered to contribute and improve our docs. ## Why Contribute? Open-source work is never done, and neither is documentation. Contributing to docs is a good way for beginners to get involved in open-source and for experienced developers to clarify more complex topics while sharing their knowledge with the community. By contributing to the Next.js docs, you're helping us build a more robust learning resource for all developers. Whether you've found a typo, a confusing section, or you've realized that a particular topic is missing, your contributions are welcomed and appreciated. ## How to Contribute The docs content can be found on the [Next.js repo](https://github.com/vercel/next.js/tree/canary/docs). To contribute, you can edit the files directly on GitHub or clone the repo and edit the files locally. ### GitHub Workflow If you're new to GitHub, we recommend reading the [GitHub Open Source Guide](https://opensource.guide/how-to-contribute/#opening-a-pull-request) to learn how to fork a repository, create a branch, and submit a pull request. > **Good to know**: The underlying docs code lives in a private codebase that is synced to the Next.js public repo. This means that you can't preview the docs locally. However, you'll see your changes on [nextjs.org](https://nextjs.org/docs) after merging a pull request. ### Writing MDX The docs are written in [MDX](https://mdxjs.com/), a markdown format that supports JSX syntax. This allows us to embed React components in the docs. See the [GitHub Markdown Guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) for a quick overview of markdown syntax. ### VSCode #### Previewing Changes Locally VSCode has a built-in markdown previewer that you can use to see your edits locally. To enable the previewer for MDX files, you'll need to add a configuration option to your user settings. Open the command palette (`⌘ + ⇧ + P` on Mac or `Ctrl + Shift + P` on Windows) and search for `Preferences: Open User Settings (JSON)`. Then, add the following line to your `settings.json` file: ```json filename="settings.json" { "files.associations": { "*.mdx": "markdown" } } ``` Next, open the command palette again, and search for `Markdown: Preview File` or `Markdown: Open Preview to the Side`. This will open a preview window where you can see your formatted changes. #### Extensions We also recommend the following extensions for VSCode users: - [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx): Intellisense and syntax highlighting for MDX. - [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode): Format MDX files on save. ### Review Process Once you've submitted your contribution, the Next.js or Developer Experience teams will review your changes, provide feedback, and merge the pull request when it's ready. Please let us know if you have any questions or need further assistance in your PR's comments. Thank you for contributing to the Next.js docs and being a part of our community! > **Tip:** Run `pnpm prettier-fix` to run Prettier before submitting your PR. ## File Structure The docs use **file-system routing**. Each folder and files inside [`/docs`](https://github.com/vercel/next.js/tree/canary/docs) represent a route segment. These segments are used to generate the URL paths, navigation, and breadcrumbs. The file structure reflects the navigation that you see on the site, and by default, navigation items are sorted alphabetically. However, we can change the order of the items by prepending a two-digit number (`00-`) to the folder or file name. For example, in the [functions API Reference](/docs/app/api-reference/functions), the pages are sorted alphabetically because it makes it easier for developers to find a specific function: ```txt 04-functions ├── after.mdx ├── cacheLife.mdx ├── cacheTag.mdx └── ... ``` But, in the [app router section](/docs/app), the files are prefixed with a two-digit number, sorted in the order developers should learn these concepts: ```txt 01-getting-started ├── 01-installation.mdx ├── 02-project-structure.mdx ├── 03-layouts-and-pages.mdx └── ... ``` To quickly find a page, you can use `⌘ + P` (Mac) or `Ctrl + P` (Windows) to open the search bar on VSCode. Then, type the slug of the page you're looking for. E.g. `installation` > **Why not use a manifest?** > > We considered using a manifest file (another popular way to generate the docs navigation), but we found that a manifest would quickly get out of sync with the files. File-system routing forces us to think about the structure of the docs and feels more native to Next.js. ## Metadata Each page has a metadata block at the top of the file separated by three dashes. ### Required Fields The following fields are **required**: | Field | Description | | ------------- | ---------------------------------------------------------------------------- | | `title` | The page's `

` title, used for SEO and OG Images. | | `description` | The page's description, used in the `` tag for SEO. | ```yaml filename="required-fields.mdx" --- title: Page Title description: Page Description --- ``` It's good practice to limit the page title to 2-3 words (e.g. Optimizing Images) and the description to 1-2 sentences (e.g. Learn how to optimize images in Next.js). ### Optional Fields The following fields are **optional**: | Field | Description | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `nav_title` | Overrides the page's title in the navigation. This is useful when the page's title is too long to fit. If not provided, the `title` field is used. | | `source` | Pulls content into a shared page. See [Shared Pages](#shared-pages). | | `related` | A list of related pages at the bottom of the document. These will automatically be turned into cards. See [Related Links](#related-links). | | `version` | A stage of development. e.g. `experimental`,`legacy`,`unstable`,`RC` | ```yaml filename="optional-fields.mdx" --- nav_title: Nav Item Title source: app/building-your-application/optimizing/images related: description: See the image component API reference. links: - app/api-reference/components/image version: experimental --- ``` ## `App` and `Pages` Docs Since most of the features in the **App Router** and **Pages Router** are completely different, their docs for each are kept in separate sections (`02-app` and `03-pages`). However, there are a few features that are shared between them. ### Shared Pages To avoid content duplication and risk the content becoming out of sync, we use the `source` field to pull content from one page into another. For example, the `` component behaves _mostly_ the same in **App** and **Pages**. Instead of duplicating the content, we can pull the content from `app/.../link.mdx` into `pages/.../link.mdx`: ```mdx filename="app/.../link.mdx" --- title: description: API reference for the component. --- This API reference will help you understand how to use the props and configuration options available for the Link Component. ``` ```mdx filename="pages/.../link.mdx" --- title: description: API reference for the component. source: app/api-reference/components/link --- {/* DO NOT EDIT THIS PAGE. */} {/* The content of this page is pulled from the source above. */} ``` We can therefore edit the content in one place and have it reflected in both sections. ### Shared Content In shared pages, sometimes there might be content that is **App Router** or **Pages Router** specific. For example, the `` component has a `shallow` prop that is only available in **Pages** but not in **App**. To make sure the content only shows in the correct router, we can wrap content blocks in an `` or `` components: ```mdx filename="app/.../link.mdx" This content is shared between App and Pages. This content will only be shown on the Pages docs. This content is shared between App and Pages. ``` You'll likely use these components for examples and code blocks. ## Code Blocks Code blocks should contain a minimum working example that can be copied and pasted. This means that the code should be able to run without any additional configuration. For example, if you're showing how to use the `` component, you should include the `import` statement and the `` component itself. ```tsx filename="app/page.tsx" import Link from 'next/link' export default function Page() { return About } ``` Always run examples locally before committing them. This will ensure that the code is up-to-date and working. ### Language and Filename Code blocks should have a header that includes the language and the `filename`. For example: ````mdx filename="code-example.mdx" ```tsx filename="app/page.tsx" export default function Page() { return

Hello, Next.js!

} ``` ```` For CLI commands, use the `package` prop to show the command for each package manager: ````mdx filename="code-example.mdx" ```bash package="pnpm" pnpm create next-app ``` ```bash package="npm" npx create-next-app@latest ``` ```bash package="yarn" yarn create next-app ``` ```bash package="bun" bun create next-app ``` ```` Most examples in the docs are written in `tsx` and `jsx`, and a few in `bash`. However, you can use any supported language, here's the [full list](https://github.com/shikijs/shiki/blob/main/docs/languages.md#all-languages). When writing JavaScript code blocks, we use the following language and extension combinations. | | Language | Extension | | ------------------------------ | ---------- | --------- | | JavaScript files with JSX code | ` ```jsx ` | .js | | JavaScript files without JSX | ` ```js ` | .js | | TypeScript files with JSX | ` ```tsx ` | .tsx | | TypeScript files without JSX | ` ```ts ` | .ts | > **Good to know**: > > - Make sure to use **`.js`** extension for JavaScript files with **JSX** code. > - For example, ` ```jsx filename="app/layout.js" ` ### TS and JS Switcher Add a language switcher to toggle between TypeScript and JavaScript. Code blocks should be TypeScript first with a JavaScript version to accommodate users. Currently, we write TS and JS examples one after the other, and link them with `switcher` prop: ````mdx filename="code-example.mdx" ```tsx filename="app/page.tsx" switcher ``` ```jsx filename="app/page.js" switcher ``` ```` > **Good to know**: We plan to automatically compile TypeScript snippets to JavaScript in the future. In the meantime, you can use [transform.tools](https://transform.tools/typescript-to-javascript). ### Line Highlighting Code lines can be highlighted. This is useful when you want to draw attention to a specific part of the code. You can highlight lines by passing a number to the `highlight` prop. **Single Line:** `highlight={1}` ```tsx filename="app/page.tsx" {1} import Link from 'next/link' export default function Page() { return About } ``` **Multiple Lines:** `highlight={1,3}` ```tsx filename="app/page.tsx" highlight={1,3} import Link from 'next/link' export default function Page() { return About } ``` **Range of Lines:** `highlight={1-5}` ```tsx filename="app/page.tsx" highlight={1-5} import Link from 'next/link' export default function Page() { return About } ``` ## Icons The following icons are available for use in the docs: ```mdx filename="mdx-icon.mdx" ``` **Output:** We do not use emojis in the docs. ## Notes For information that is important but not critical, use notes. Notes are a good way to add information without distracting the user from the main content. ```mdx filename="notes.mdx" > **Good to know**: This is a single line note. > **Good to know**: > > - We also use this format for multi-line notes. > - There are sometimes multiple items worth knowing or keeping in mind. ``` **Output:** > **Good to know**: This is a single line note. > **Good to know**: > > - We also use this format for multi-line notes. > - There are sometimes multiple items worth knowing or keeping in mind. ## Related Links Related Links guide the user's learning journey by adding links to logical next steps. - Links will be displayed in cards under the main content of the page. - Links will be automatically generated for pages that have child pages. Create related links using the `related` field in the page's metadata. ```yaml filename="example.mdx" --- related: description: Learn how to quickly get started with your first application. links: - app/building-your-application/routing/defining-routes - app/building-your-application/data-fetching - app/api-reference/file-conventions/page --- ``` ### Nested Fields | Field | Required? | Description | | ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | Optional | The title of the card list. Defaults to **Next Steps**. | | `description` | Optional | The description of the card list. | | `links` | Required | A list of links to other doc pages. Each list item should be a relative URL path (without a leading slash) e.g. `app/api-reference/file-conventions/page` | ## Diagrams Diagrams are a great way to explain complex concepts. We use [Figma](https://www.figma.com/) to create diagrams, following Vercel's design guide. The diagrams currently live in the `/public` folder in our private Next.js site. If you'd like to update or add a diagram, please open a [GitHub issue](https://github.com/vercel/next.js/issues/new?assignees=&labels=template%3A+documentation&projects=&template=4.docs_request.yml&title=Docs%3A+) with your ideas. ## Custom Components and HTML These are the React Components available for the docs: `` (next/image), ``, ``, ``, and ``. We do not allow raw HTML in the docs besides the `
` tag. If you have ideas for new components, please open a [GitHub issue](https://github.com/vercel/next.js/issues/new/choose). ## Style Guide This section contains guidelines for writing docs for those who are new to technical writing. ### Page Templates While we don't have a strict template for pages, there are page sections you'll see repeated across the docs: - **Overview:** The first paragraph of a page should tell the user what the feature is and what it's used for. Followed by a minimum working example or its API reference. - **Convention:** If the feature has a convention, it should be explained here. - **Examples**: Show how the feature can be used with different use cases. - **API Tables**: API Pages should have an overview table at the top of the page with jump-to-section links (when possible). - **Next Steps (Related Links)**: Add links to related pages to guide the user's learning journey. Feel free to add these sections as needed. ### Page Types Docs pages are also split into two categories: Conceptual and Reference. - **Conceptual** pages are used to explain a concept or feature. They are usually longer and contain more information than reference pages. In the Next.js docs, conceptual pages are found in the **Building Your Application** section. - **Reference** pages are used to explain a specific API. They are usually shorter and more focused. In the Next.js docs, reference pages are found in the **API Reference** section. > **Good to know**: Depending on the page you're contributing to, you may need to follow a different voice and style. For example, conceptual pages are more instructional and use the word _you_ to address the user. Reference pages are more technical, they use more imperative words like "create, update, accept" and tend to omit the word _you_. ### Voice Here are some guidelines to maintain a consistent style and voice across the docs: - Write clear, concise sentences. Avoid tangents. - If you find yourself using a lot of commas, consider breaking the sentence into multiple sentences or use a list. - Swap out complex words for simpler ones. For example, _use_ instead of _utilize_. - Be mindful with the word _this_. It can be ambiguous and confusing, don't be afraid to repeat the subject of the sentence if unclear. - For example, _Next.js uses React_ instead of _Next.js uses this_. - Use an active voice instead of passive. An active sentence is easier to read. - For example, _Next.js uses React_ instead of _React is used by Next.js_. If you find yourself using words like _was_ and _by_ you may be using a passive voice. - Avoid using words like _easy_, _quick_, _simple_, _just_, etc. This is subjective and can be discouraging to users. - Avoid negative words like _don't_, _can't_, _won't_, etc. This can be discouraging to readers. - For example, _"You can use the `Link` component to create links between pages"_ instead of _"Don't use the `` tag to create links between pages"_. - Write in second person (you/your). This is more personal and engaging. - Use gender-neutral language. Use _developers_, _users_, or _readers_, when referring to the audience. - If adding code examples, ensure they are properly formatted and working. While these guidelines are not exhaustive, they should help you get started. If you'd like to dive deeper into technical writing, check out the [Google Technical Writing Course](https://developers.google.com/tech-writing/overview). --- Thank you for contributing to the docs and being part of the Next.js community! {/* To do: Latest Contributors Component */} --- ### 04 Community 02 Rspack (`docs/04-community/02-rspack.mdx`) --- title: Rspack Integration nav_title: Rspack description: Use the `next-rspack` plugin to bundle your Next.js with Rspack. version: experimental --- The Rspack team has created a community plugin for Next.js, which is part of a [partnering effort](https://rspack.rs/blog/rspack-next-partner) with the Rspack team. This plugin is currently experimental. Please use this [discussion thread](https://github.com/vercel/next.js/discussions/77800) to give feedback on any issues you encounter. Learn more on the [Rspack docs](https://rspack.rs/guide/tech/next) and try out [this example](https://github.com/vercel/next.js/tree/canary/examples/with-rspack). --- ### 01 App 01 Getting Started 01 Installation (`docs/01-app/01-getting-started/01-installation.mdx`) --- title: Installation description: Learn how to create a new Next.js application with the `create-next-app` CLI, and set up TypeScript, ESLint, and Module Path Aliases. --- {/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} Create a new Next.js app and run it locally. ## Quick start 1. Create a new Next.js app named `my-app` 2. `cd my-app` and start the dev server. 3. Visit `http://localhost:3000`. ```bash package="pnpm" pnpm create next-app@latest my-app --yes cd my-app pnpm dev ``` ```bash package="npm" npx create-next-app@latest my-app --yes cd my-app npm run dev ``` ```bash package="yarn" yarn create next-app@latest my-app --yes cd my-app yarn dev ``` ```bash package="bun" bun create next-app@latest my-app --yes cd my-app bun dev ``` - `--yes` skips prompts using saved preferences or defaults. The default setup enables TypeScript, Tailwind CSS, ESLint, App Router, and Turbopack, with import alias `@/*`, and includes `AGENTS.md` to guide coding agents to write up-to-date Next.js code. ## System requirements Before you begin, make sure your development environment meets the following requirements: - Minimum Node.js version: [20.9](https://nodejs.org/) - Operating systems: macOS, Windows (including WSL), and Linux. ## Supported browsers Next.js supports modern browsers with zero configuration. - Chrome 111+ - Edge 111+ - Firefox 111+ - Safari 16.4+ Learn more about [browser support](/docs/architecture/supported-browsers), including how to configure polyfills and target specific browsers. ## Create with the CLI The quickest way to create a new Next.js app is using [`create-next-app`](/docs/app/api-reference/cli/create-next-app), which sets up everything automatically for you. To create a project, run: ```bash package="pnpm" pnpm create next-app ``` ```bash package="npm" npx create-next-app@latest ``` ```bash package="yarn" yarn create next-app ``` ```bash package="bun" bun create next-app ``` On installation, you'll see the following prompts: ```txt filename="Terminal" What is your project named? my-app Would you like to use the recommended Next.js defaults? Yes, use recommended defaults - TypeScript, ESLint, No React Compiler, Tailwind CSS, No src/ directory, App Router, Cache Components, AGENTS.md No, reuse previous settings No, customize settings - Choose your own preferences ``` If you choose to `customize settings`, you'll see the following prompts: ```txt filename="Terminal" Would you like to use TypeScript? No / Yes Which linter would you like to use? ESLint / Biome / None Would you like to use React Compiler? No / Yes Would you like to use Tailwind CSS? No / Yes Would you like your code inside a `src/` directory? No / Yes Would you like to use App Router? (recommended) No / Yes Would you like to use Cache Components? No / Yes Would you like to customize the import alias (`@/*` by default)? No / Yes What import alias would you like configured? @/* Would you like to include AGENTS.md to guide coding agents to write up-to-date Next.js code? No / Yes ``` After the prompts, [`create-next-app`](/docs/app/api-reference/cli/create-next-app) will create a folder with your project name and install the required dependencies. ## Manual installation To manually create a new Next.js app, install the required packages: ```bash package="pnpm" pnpm i next@latest react@latest react-dom@latest ``` ```bash package="npm" npm i next@latest react@latest react-dom@latest ``` ```bash package="yarn" yarn add next@latest react@latest react-dom@latest ``` ```bash package="bun" bun add next@latest react@latest react-dom@latest ``` > **Good to know**: > > - The `App Router` uses [React canary releases](https://react.dev/blog/2023/05/03/react-canaries) built-in, which include all the stable React 19 changes, as well as newer features being validated in frameworks, but you should still declare react and react-dom in package.json for tooling and ecosystem compatibility. > - The `Pages Router` uses the React version from your `package.json`. Then, add the following scripts to your `package.json` file: ```json filename="package.json" { "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "eslint", "lint:fix": "eslint --fix" } } ``` These scripts refer to the different stages of developing an application: - `next dev`: Starts the development server using Turbopack (default bundler). - `next build`: Builds the application for production. - `next start`: Starts the production server. - `eslint`: Runs ESLint. Turbopack is now the default bundler. To use Webpack run `next dev --webpack` or `next build --webpack`. See the [Turbopack docs](/docs/app/api-reference/turbopack) for configuration details. ### Create the `app` directory Next.js uses file-system routing, which means the routes in your application are determined by how you structure your files. Create an `app` folder. Then, inside `app`, create a `layout.tsx` file. This file is the [root layout](/docs/app/api-reference/file-conventions/layout#root-layout). It's required and must contain the `` and `` tags. ```tsx filename="app/layout.tsx" switcher export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( {children} ) } ``` ```jsx filename="app/layout.js" switcher export default function RootLayout({ children }) { return ( {children} ) } ``` Create a home page `app/page.tsx` with some initial content: ```tsx filename="app/page.tsx" switcher export default function Page() { return

Hello, Next.js!

} ``` ```jsx filename="app/page.js" switcher export default function Page() { return

Hello, Next.js!

} ``` Both `layout.tsx` and `page.tsx` will be rendered when the user visits the root of your application (`/`). App Folder Structure > **Good to know**: > > - If you forget to create the root layout, Next.js will automatically create this file when running the development server with `next dev`. > - You can optionally use a [`src` folder](/docs/app/api-reference/file-conventions/src-folder) in the root of your project to separate your application's code from configuration files. ### Create the `pages` directory Next.js uses file-system routing, which means the routes in your application are determined by how you structure your files. Create a `pages` directory at the root of your project. Then, add an `index.tsx` file inside your `pages` folder. This will be your home page (`/`): ```tsx filename="pages/index.tsx" switcher export default function Page() { return

Hello, Next.js!

} ``` ```jsx filename="pages/index.js" switcher export default function Page() { return

Hello, Next.js!

} ``` Next, add an `_app.tsx` file inside `pages/` to define the global layout. Learn more about the [custom App file](/docs/pages/building-your-application/routing/custom-app). ```tsx filename="pages/_app.tsx" switcher import type { AppProps } from 'next/app' export default function App({ Component, pageProps }: AppProps) { return } ``` ```jsx filename="pages/_app.js" switcher export default function App({ Component, pageProps }) { return } ``` Finally, add a `_document.tsx` file inside `pages/` to control the initial response from the server. Learn more about the [custom Document file](/docs/pages/building-your-application/routing/custom-document). ```tsx filename="pages/_document.tsx" switcher import { Html, Head, Main, NextScript } from 'next/document' export default function Document() { return (
) } ``` ```jsx filename="pages/_document.js" switcher import { Html, Head, Main, NextScript } from 'next/document' export default function Document() { return (
) } ``` ### Create the `public` folder (optional) Create a [`public` folder](/docs/app/api-reference/file-conventions/public-folder) at the root of your project to store static assets such as images, fonts, etc. Files inside `public` can then be referenced by your code starting from the base URL (`/`). You can then reference these assets using the root path (`/`). For example, `public/profile.png` can be referenced as `/profile.png`: ```tsx filename="app/page.tsx" highlight={4} switcher import Image from 'next/image' export default function Page() { return Profile } ``` ```jsx filename="app/page.js" highlight={4} switcher import Image from 'next/image' export default function Page() { return Profile } ``` ## Run the development server 1. Run `npm run dev` to start the development server. 2. Visit `http://localhost:3000` to view your application. 3. Edit the `app/page.tsx``pages/index.tsx` file and save it to see the updated result in your browser. ## Set up TypeScript > Minimum TypeScript version: `v5.1.0` Next.js comes with built-in TypeScript support. To add TypeScript to your project, rename a file to `.ts` / `.tsx` and run `next dev`. Next.js will automatically install the necessary dependencies and add a `tsconfig.json` file with the recommended config options. ### IDE Plugin Next.js includes a custom TypeScript plugin and type checker, which VSCode and other code editors can use for advanced type-checking and auto-completion. You can enable the plugin in VS Code by: 1. Opening the command palette (`Ctrl/⌘` + `Shift` + `P`) 2. Searching for "TypeScript: Select TypeScript Version" 3. Selecting "Use Workspace Version" TypeScript Command Palette See the [TypeScript reference](/docs/app/api-reference/config/typescript) page for more information. ## Set up your editor The App Router names files by convention, like `page.tsx`, `layout.tsx`, and `route.ts`, so your editor quickly fills with same-named tabs. Label each tab with its enclosing folders, like `blog/[id]`, so you can tell them apart. In VS Code 1.88+ or Cursor, add [custom editor labels](https://code.visualstudio.com/updates/v1_88#_customize-editor-labels) to `.vscode/settings.json`. Labeling two folders deep keeps dynamic routes like `blog/[id]/page.tsx` from all collapsing to the same `[id]` label: ```json filename=".vscode/settings.json" { "workbench.editor.customLabels.patterns": { "**/app/**/page.tsx": "${dirname(1)}/${dirname} - page.tsx", "**/app/**/layout.tsx": "${dirname(1)}/${dirname} - layout.tsx", "**/app/**/loading.tsx": "${dirname(1)}/${dirname} - loading.tsx", "**/app/**/error.tsx": "${dirname(1)}/${dirname} - error.tsx", "**/app/**/not-found.tsx": "${dirname(1)}/${dirname} - not-found.tsx", "**/app/**/template.tsx": "${dirname(1)}/${dirname} - template.tsx", "**/app/**/default.tsx": "${dirname(1)}/${dirname} - default.tsx", "**/app/**/route.ts": "${dirname(1)}/${dirname} - route.ts" } } ``` Or copy this prompt to have your coding agent set it up: ```prompt Set up custom editor labels so my Next.js App Router files are easy to tell apart. Read https://nextjs.org/docs/app/getting-started/installation#set-up-your-editor and add the workbench.editor.customLabels.patterns config shown there to my .vscode/settings.json, creating the file if it doesn't exist. Adjust the labels to taste. If I use a different editor, apply the equivalent setting or tell me it's automatic, and leave my other settings untouched. ``` > **Good to know:** JetBrains IDEs (WebStorm, IntelliJ) show the folder for same-named files automatically, so no setup is needed. ## Set up linting Next.js supports linting with either ESLint or Biome. Choose a linter and run it directly via `package.json` scripts. - Use **ESLint** (comprehensive rules): ```json filename="package.json" { "scripts": { "lint": "eslint", "lint:fix": "eslint --fix" } } ``` - Or use **Biome** (fast linter + formatter): ```json filename="package.json" { "scripts": { "lint": "biome check", "format": "biome format --write" } } ``` If your project previously used `next lint`, migrate your scripts to the ESLint CLI with the codemod: ```bash filename="Terminal" npx @next/codemod@canary next-lint-to-eslint-cli . ``` If you use ESLint, create an explicit config (recommended `eslint.config.mjs`). ESLint supports both [the legacy `.eslintrc.*` and the newer `eslint.config.mjs` formats](https://eslint.org/docs/latest/use/configure/configuration-files#configuring-eslint). See the [ESLint API reference](/docs/app/api-reference/config/eslint#with-core-web-vitals) for a recommended setup. > **Good to know**: Starting with Next.js 16, `next build` no longer runs the linter automatically. Instead, you can run your linter through NPM scripts. See the [ESLint Plugin](/docs/app/api-reference/config/eslint) page for more information. ## Set up Absolute Imports and Module Path Aliases Next.js has in-built support for the `"paths"` and `"baseUrl"` options of `tsconfig.json` and `jsconfig.json` files. These options allow you to alias project directories to absolute paths, making it easier and cleaner to import modules. For example: ```jsx // Before import { Button } from '../../../components/button' // After import { Button } from '@/components/button' ``` To configure absolute imports, add the `baseUrl` configuration option to your `tsconfig.json` or `jsconfig.json` file. For example: ```json filename="tsconfig.json or jsconfig.json" { "compilerOptions": { "baseUrl": "src/" } } ``` In addition to configuring the `baseUrl` path, you can use the `"paths"` option to `"alias"` module paths. For example, the following configuration maps `@/components/*` to `components/*`: ```json filename="tsconfig.json or jsconfig.json" { "compilerOptions": { "baseUrl": "src/", "paths": { "@/styles/*": ["styles/*"], "@/components/*": ["components/*"] } } } ``` Each of the `"paths"` are relative to the `baseUrl` location. ## Upgrade your Next.js app Keep your Next.js version up to date. Each release ships security patches, bug fixes, and performance optimizations alongside new features, and staying current keeps every individual upgrade small. Run the `upgrade` command: ```bash package="pnpm" pnpm next upgrade ``` ```bash package="npm" npx next upgrade ``` ```bash package="yarn" yarn next upgrade ``` ```bash package="bun" bunx next upgrade ``` Upgrading also updates the documentation bundled inside the `next` package at `node_modules/next/dist/docs/`. New features arrive with their docs, and existing pages pick up new guidance and pitfalls discovered along the way. [AI coding agents](/docs/app/guides/ai-agents) in your project then work from the version you have installed rather than their training data. To have a coding agent perform and verify the upgrade, run `npx next@canary upgrade --agent=latest`. See [Upgrade with a coding agent](/docs/app/guides/upgrading/agent-upgrade) for other policies. See [Upgrading](/docs/app/getting-started/upgrading) for version guides and manual upgrade steps, or the [preview docs](https://preview.nextjs.org) to explore features before they ship in a stable version. --- ### 01 App 01 Getting Started 02 Project Structure (`docs/01-app/01-getting-started/02-project-structure.mdx`) --- title: Project structure and organization nav_title: Project Structure description: Learn the folder and file conventions in Next.js, and how to organize your project. --- This page provides an overview of **all** the folder and file conventions in Next.js, and recommendations for organizing your project. ## Folder and file conventions ### Top-level folders Top-level folders are used to organize your application's code and static assets. Route segments to path segments | | | | ------------------------------------------------------------------ | ---------------------------------- | | [`app`](/docs/app) | App Router | | [`pages`](/docs/pages/building-your-application/routing) | Pages Router | | [`public`](/docs/app/api-reference/file-conventions/public-folder) | Static assets to be served | | [`src`](/docs/app/api-reference/file-conventions/src-folder) | Optional application source folder | ### Top-level files Top-level files are used to configure your application, manage dependencies, run proxy, integrate monitoring tools, and define environment variables. | | | | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | **Next.js** | | | [`next.config.js`](/docs/app/api-reference/config/next-config-js) | Configuration file for Next.js | | [`package.json`](/docs/app/getting-started/installation#manual-installation) | Project dependencies and scripts | | [`instrumentation.ts`](/docs/app/guides/instrumentation) | OpenTelemetry and Instrumentation file | | [`proxy.ts`](/docs/app/api-reference/file-conventions/proxy) | Next.js request proxy | | [`.env`](/docs/app/guides/environment-variables) | Environment variables (should not be tracked by version control) | | [`.env.local`](/docs/app/guides/environment-variables) | Local environment variables (should not be tracked by version control) | | [`.env.production`](/docs/app/guides/environment-variables) | Production environment variables (should not be tracked by version control) | | [`.env.development`](/docs/app/guides/environment-variables) | Development environment variables (should not be tracked by version control) | | [`eslint.config.mjs`](/docs/app/api-reference/config/eslint) | Configuration file for ESLint | | `.gitignore` | Git files and folders to ignore | | [`next-env.d.ts`](/docs/app/api-reference/config/typescript#next-envdts) | TypeScript declaration file for Next.js (should not be tracked by version control) | | `tsconfig.json` | Configuration file for TypeScript | | `jsconfig.json` | Configuration file for JavaScript | ### Routing Files Add `page` to expose a route, `layout` for shared UI such as header, nav, or footer, `loading` for skeletons, `error` for error boundaries, and `route` for APIs. | | | | | ----------------------------------------------------------------------------- | ------------------- | ---------------------------- | | [`layout`](/docs/app/api-reference/file-conventions/layout) | `.js` `.jsx` `.tsx` | Layout | | [`page`](/docs/app/api-reference/file-conventions/page) | `.js` `.jsx` `.tsx` | Page | | [`loading`](/docs/app/api-reference/file-conventions/loading) | `.js` `.jsx` `.tsx` | Loading UI | | [`not-found`](/docs/app/api-reference/file-conventions/not-found) | `.js` `.jsx` `.tsx` | Not found UI | | [`error`](/docs/app/api-reference/file-conventions/error) | `.js` `.jsx` `.tsx` | Error UI | | [`global-error`](/docs/app/api-reference/file-conventions/error#global-error) | `.js` `.jsx` `.tsx` | Global error UI | | [`route`](/docs/app/api-reference/file-conventions/route) | `.js` `.ts` | API endpoint | | [`template`](/docs/app/api-reference/file-conventions/template) | `.js` `.jsx` `.tsx` | Re-rendered layout | | [`default`](/docs/app/api-reference/file-conventions/default) | `.js` `.jsx` `.tsx` | Parallel route fallback page | ### Nested routes Folders define URL segments. Nesting folders nests segments. Layouts at any level wrap their child segments. A route becomes public when a `page` or `route` file exists. | Path | URL pattern | Notes | | --------------------------- | --------------- | ----------------------------- | | `app/layout.tsx` | — | Root layout wraps all routes | | `app/blog/layout.tsx` | — | Wraps `/blog` and descendants | | `app/page.tsx` | `/` | Public route | | `app/blog/page.tsx` | `/blog` | Public route | | `app/blog/authors/page.tsx` | `/blog/authors` | Public route | ### Dynamic routes Parameterize segments with square brackets. Use `[segment]` for a single param, `[...segment]` for catch‑all, and `[[...segment]]` for optional catch‑all. Access values via the [`params`](/docs/app/api-reference/file-conventions/page#params-optional) prop. | Path | URL pattern | | ------------------------------- | -------------------------------------------------------------------- | | `app/blog/[slug]/page.tsx` | `/blog/my-first-post` | | `app/shop/[...slug]/page.tsx` | `/shop/clothing`, `/shop/clothing/shirts` | | `app/docs/[[...slug]]/page.tsx` | `/docs`, `/docs/layouts-and-pages`, `/docs/api-reference/use-router` | ### Route groups and private folders Organize code without changing URLs with route groups [`(group)`](/docs/app/api-reference/file-conventions/route-groups#convention), and colocate non-routable files with private folders [`_folder`](#private-folders). | Path | URL pattern | Notes | | ------------------------------- | ----------- | ----------------------------------------- | | `app/(marketing)/page.tsx` | `/` | Group omitted from URL | | `app/(shop)/cart/page.tsx` | `/cart` | Share layouts within `(shop)` | | `app/blog/_components/Post.tsx` | — | Not routable; safe place for UI utilities | | `app/blog/_lib/data.ts` | — | Not routable; safe place for utils | ### Parallel and Intercepted Routes These features fit specific UI patterns, such as slot-based layouts or modal routing. Use `@slot` for named slots rendered by a parent layout. Use intercept patterns to render another route inside the current layout without changing the URL, for example, to show a details view as a modal over a list. | Pattern (docs) | Meaning | Typical use case | | ------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------- | | [`@folder`](/docs/app/api-reference/file-conventions/parallel-routes#slots) | Named slot | Sidebar + main content | | [`(.)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept same level | Preview sibling route in a modal | | [`(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept parent | Open a child of the parent as an overlay | | [`(..)(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept two levels | Deeply nested overlay | | [`(...)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept from root | Show arbitrary route in current view | ### Metadata file conventions #### App icons | | | | | --------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------ | | [`favicon`](/docs/app/api-reference/file-conventions/metadata/app-icons#favicon) | `.ico` | Favicon file | | [`icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#icon) | `.ico` `.jpg` `.jpeg` `.png` `.svg` | App Icon file | | [`icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#generate-icons-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated App Icon | | [`apple-icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#apple-icon) | `.jpg` `.jpeg` `.png` | Apple App Icon file | | [`apple-icon`](/docs/app/api-reference/file-conventions/metadata/app-icons#generate-icons-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated Apple App Icon | #### Open Graph and Twitter images | | | | | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------------- | | [`opengraph-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#opengraph-image) | `.jpg` `.jpeg` `.png` `.gif` | Open Graph image file | | [`opengraph-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#generate-images-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated Open Graph image | | [`twitter-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#twitter-image) | `.jpg` `.jpeg` `.png` `.gif` | Twitter image file | | [`twitter-image`](/docs/app/api-reference/file-conventions/metadata/opengraph-image#generate-images-using-code-js-ts-tsx) | `.js` `.ts` `.tsx` | Generated Twitter image | #### SEO | | | | | ------------------------------------------------------------------------------------------------------------ | ----------- | --------------------- | | [`sitemap`](/docs/app/api-reference/file-conventions/metadata/sitemap#sitemap-files-xml) | `.xml` | Sitemap file | | [`sitemap`](/docs/app/api-reference/file-conventions/metadata/sitemap#generating-a-sitemap-using-code-js-ts) | `.js` `.ts` | Generated Sitemap | | [`robots`](/docs/app/api-reference/file-conventions/metadata/robots#static-robotstxt) | `.txt` | Robots file | | [`robots`](/docs/app/api-reference/file-conventions/metadata/robots#generate-a-robots-file) | `.js` `.ts` | Generated Robots file | ### File conventions | | | | | ----------------------------------------------------------------------------------------------------------- | ------------------- | ----------------- | | [`_app`](/docs/pages/building-your-application/routing/custom-app) | `.js` `.jsx` `.tsx` | Custom App | | [`_document`](/docs/pages/building-your-application/routing/custom-document) | `.js` `.jsx` `.tsx` | Custom Document | | [`_error`](/docs/pages/building-your-application/routing/custom-error#more-advanced-error-page-customizing) | `.js` `.jsx` `.tsx` | Custom Error Page | | [`404`](/docs/pages/building-your-application/routing/custom-error#404-page) | `.js` `.jsx` `.tsx` | 404 Error Page | | [`500`](/docs/pages/building-your-application/routing/custom-error#500-page) | `.js` `.jsx` `.tsx` | 500 Error Page | ### Routes | | | | | ---------------------------------------------------------------------------------------------- | ------------------- | ----------- | | **Folder convention** | | | | [`index`](/docs/pages/building-your-application/routing/pages-and-layouts#index-routes) | `.js` `.jsx` `.tsx` | Home page | | [`folder/index`](/docs/pages/building-your-application/routing/pages-and-layouts#index-routes) | `.js` `.jsx` `.tsx` | Nested page | | **File convention** | | | | [`index`](/docs/pages/building-your-application/routing/pages-and-layouts#index-routes) | `.js` `.jsx` `.tsx` | Home page | | [`file`](/docs/pages/building-your-application/routing/pages-and-layouts) | `.js` `.jsx` `.tsx` | Nested page | ### Dynamic routes | | | | | ----------------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------- | | **Folder convention** | | | | [`[folder]/index`](/docs/pages/building-your-application/routing/dynamic-routes) | `.js` `.jsx` `.tsx` | Dynamic route segment | | [`[...folder]/index`](/docs/pages/building-your-application/routing/dynamic-routes#catch-all-segments) | `.js` `.jsx` `.tsx` | Catch-all route segment | | [`[[...folder]]/index`](/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | `.js` `.jsx` `.tsx` | Optional catch-all route segment | | **File convention** | | | | [`[file]`](/docs/pages/building-your-application/routing/dynamic-routes) | `.js` `.jsx` `.tsx` | Dynamic route segment | | [`[...file]`](/docs/pages/building-your-application/routing/dynamic-routes#catch-all-segments) | `.js` `.jsx` `.tsx` | Catch-all route segment | | [`[[...file]]`](/docs/pages/building-your-application/routing/dynamic-routes#optional-catch-all-segments) | `.js` `.jsx` `.tsx` | Optional catch-all route segment | ## Organizing your project Next.js is **unopinionated** about how you organize and colocate your project files. But it does provide several features to help you organize your project. ### Component hierarchy The components defined in special files are rendered in a specific hierarchy: - `layout.js` - `template.js` - `error.js` (React error boundary) - `loading.js` (React suspense boundary) - `not-found.js` (React error boundary for "not found" UI) - `page.js` or nested `layout.js` Component Hierarchy for File Conventions The components are rendered recursively in nested routes, meaning the components of a route segment will be nested **inside** the components of its parent segment. Nested File Conventions Component Hierarchy ### Colocation In the `app` directory, nested folders define route structure. Each folder represents a route segment that is mapped to a corresponding segment in a URL path. However, even though route structure is defined through folders, a route is **not publicly accessible** until a `page.js` or `route.js` file is added to a route segment. A diagram showing how a route is not publicly accessible until a page.js or route.js file is added to a route segment. And, even when a route is made publicly accessible, only the **content returned** by `page.js` or `route.js` is sent to the client. A diagram showing how page.js and route.js files make routes publicly accessible. This means that **project files** can be **safely colocated** inside route segments in the `app` directory without accidentally being routable. A diagram showing colocated project files are not routable even when a segment contains a page.js or route.js file. > **Good to know**: While you **can** colocate your project files in `app` you don't **have** to. If you prefer, you can [keep them outside the `app` directory](#store-project-files-outside-of-app). ### Private folders Private folders can be created by prefixing a folder with an underscore: `_folderName` This indicates the folder is a private implementation detail and should not be considered by the routing system, thereby **opting the folder and all its subfolders** out of routing. An example folder structure using private folders Since files in the `app` directory can be [safely colocated by default](#colocation), private folders are not required for colocation. However, they can be useful for: - Separating UI logic from routing logic. - Consistently organizing internal files across a project and the Next.js ecosystem. - Sorting and grouping files in code editors. - Avoiding potential naming conflicts with future Next.js file conventions. > **Good to know**: > > - While not a framework convention, you might also consider marking files outside private folders as "private" using the same underscore pattern. > - You can create URL segments that start with an underscore by prefixing the folder name with `%5F` (the URL-encoded form of an underscore): `%5FfolderName`. > - If you don't use private folders, it would be helpful to know Next.js [special file conventions](/docs/app/getting-started/project-structure#routing-files) to prevent unexpected naming conflicts. ### Route groups Route groups can be created by wrapping a folder in parenthesis: `(folderName)` This indicates the folder is for organizational purposes and should **not be included** in the route's URL path. An example folder structure using route groups Route groups are useful for: - Organizing routes by site section, intent, or team. e.g. marketing pages, admin pages, etc. - Enabling nested layouts in the same route segment level: - [Creating multiple nested layouts in the same segment, including multiple root layouts](#creating-multiple-root-layouts) - [Adding a layout to a subset of routes in a common segment](#opting-specific-segments-into-a-layout) ### `src` folder Next.js supports storing application code (including `app`) inside an optional [`src` folder](/docs/app/api-reference/file-conventions/src-folder). This separates application code from project configuration files which mostly live in the root of a project. An example folder structure with the `src` folder ## Examples The following section lists a very high-level overview of common strategies. The simplest takeaway is to choose a strategy that works for you and your team and be consistent across the project. > **Good to know**: In our examples below, we're using `components` and `lib` folders as generalized placeholders, their naming has no special framework significance and your projects might use other folders like `ui`, `utils`, `hooks`, `styles`, etc. ### Store project files outside of `app` This strategy stores all application code in shared folders in the **root of your project** and keeps the `app` directory purely for routing purposes. An example folder structure with project files outside of app ### Store project files in top-level folders inside of `app` This strategy stores all application code in shared folders in the **root of the `app` directory**. An example folder structure with project files inside app ### Split project files by feature or route This strategy stores globally shared application code in the root `app` directory and **splits** more specific application code into the route segments that use them. An example folder structure with project files split by feature or route ### Organize routes without affecting the URL path To organize routes without affecting the URL, create a group to keep related routes together. The folders in parenthesis will be omitted from the URL (e.g. `(marketing)` or `(shop)`). Organizing Routes with Route Groups Even though routes inside `(marketing)` and `(shop)` share the same URL hierarchy, you can create a different layout for each group by adding a `layout.js` file inside their folders. These layouts nest within the existing app layout. Route Groups with Multiple Layouts ### Opting specific segments into a layout To opt specific routes into a layout, create a new route group (e.g. `(shop)`) and move the routes that share the same layout into the group (e.g. `account` and `cart`). The routes outside of the group will not share the layout (e.g. `checkout`). Route Groups with Opt-in Layouts ### Opting for loading skeletons on a specific route To apply a [loading skeleton](/docs/app/api-reference/file-conventions/loading) via a `loading.js` file to a specific route, create a new route group (e.g., `/(overview)`) and then move your `loading.tsx` inside that route group. Folder structure showing a loading.tsx and a page.tsx inside the route group Now, the `loading.tsx` file will only apply to your dashboard → overview page instead of all your dashboard pages without affecting the URL path structure. ### Creating multiple root layouts To create multiple [root layouts](/docs/app/api-reference/file-conventions/layout#root-layout), remove the top-level `layout.js` file, and add a `layout.js` file inside each route group. This is useful for partitioning an application into sections that have a completely different UI or experience. The `` and `` tags need to be added to each root layout. Route Groups with Multiple Root Layouts In the example above, both `(marketing)` and `(shop)` have their own root layout. --- ### 01 App 01 Getting Started 03 Layouts And Pages (`docs/01-app/01-getting-started/03-layouts-and-pages.mdx`) --- title: Layouts and Pages description: Learn how to create your first pages and layouts, and link between them with the Link component. related: title: API Reference description: Learn more about the features mentioned in this page by reading the API Reference. links: - app/getting-started/linking-and-navigating - app/api-reference/file-conventions/layout - app/api-reference/file-conventions/page - app/api-reference/components/link - app/api-reference/file-conventions/dynamic-routes --- Next.js uses **file-system based routing**, meaning you can use folders and files to define routes. This page will guide you through how to create layouts and pages, and link between them. ## Creating a page A **page** is UI that is rendered on a specific route. To create a page, add a [`page` file](/docs/app/api-reference/file-conventions/page) inside the `app` directory and default export a React component. For example, to create an index page (`/`): page.js special file ```tsx filename="app/page.tsx" switcher export default function Page() { return

Hello Next.js!

} ``` ```jsx filename="app/page.js" switcher export default function Page() { return

Hello Next.js!

} ``` ## Creating a layout A layout is UI that is **shared** between multiple pages. On navigation, layouts preserve state, remain interactive, and do not rerender. You can define a layout by default exporting a React component from a [`layout` file](/docs/app/api-reference/file-conventions/layout). The component should accept a `children` prop which can be a page or another [layout](#nesting-layouts). For example, to create a layout that accepts your index page as child, add a `layout` file inside the `app` directory: layout.js special file ```tsx filename="app/layout.tsx" switcher export default function DashboardLayout({ children, }: { children: React.ReactNode }) { return ( {/* Layout UI */} {/* Place children where you want to render a page or nested layout */}
{children}
) } ``` ```jsx filename="app/layout.js" switcher export default function DashboardLayout({ children }) { return ( {/* Layout UI */} {/* Place children where you want to render a page or nested layout */}
{children}
) } ``` The layout above is called a [root layout](/docs/app/api-reference/file-conventions/layout#root-layout) because it's defined at the root of the `app` directory. The root layout is **required** and must contain `html` and `body` tags. ## Creating a nested route A nested route is a route composed of multiple URL segments. For example, the `/blog/[slug]` route is composed of three segments: - `/` (Root Segment) - `blog` (Segment) - `[slug]` (Leaf Segment) In Next.js: - **Folders** are used to define the route segments that map to URL segments. - **Files** (like `page` and `layout`) are used to create UI that is shown for a segment. To create nested routes, you can nest folders inside each other. For example, to add a route for `/blog`, create a folder called `blog` in the `app` directory. Then, to make `/blog` publicly accessible, add a `page.tsx` file: File hierarchy showing blog folder and a page.js file ```tsx filename="app/blog/page.tsx" switcher // Dummy imports import { getPosts } from '@/lib/posts' import { Post } from '@/ui/post' export default async function Page() { const posts = await getPosts() return (
    {posts.map((post) => ( ))}
) } ``` ```jsx filename="app/blog/page.js" switcher // Dummy imports import { getPosts } from '@/lib/posts' import { Post } from '@/ui/post' export default async function Page() { const posts = await getPosts() return (
    {posts.map((post) => ( ))}
) } ``` You can continue nesting folders to create nested routes. For example, to create a route for a specific blog post, create a new `[slug]` folder inside `blog` and add a `page` file: File hierarchy showing blog folder with a nested slug folder and a page.js file ```tsx filename="app/blog/[slug]/page.tsx" switcher export function generateStaticParams() {} export default function Page() { return

Hello, Blog Post Page!

} ``` ```jsx filename="app/blog/[slug]/page.js" switcher export function generateStaticParams() {} export default function Page() { return

Hello, Blog Post Page!

} ``` Wrapping a folder name in square brackets (e.g. `[slug]`) creates a [dynamic route segment](/docs/app/api-reference/file-conventions/dynamic-routes) which is used to generate multiple pages from data. e.g. blog posts, product pages, etc. ## Nesting layouts By default, layouts in the folder hierarchy are also nested, which means they wrap child layouts via their `children` prop. You can nest layouts by adding `layout` inside specific route segments (folders). For example, to create a layout for the `/blog` route, add a new `layout` file inside the `blog` folder. File hierarchy showing root layout wrapping the blog layout ```tsx filename="app/blog/layout.tsx" switcher export default function BlogLayout({ children, }: { children: React.ReactNode }) { return
{children}
} ``` ```jsx filename="app/blog/layout.js" switcher export default function BlogLayout({ children }) { return
{children}
} ``` If you were to combine the two layouts above, the root layout (`app/layout.js`) would wrap the blog layout (`app/blog/layout.js`), which would wrap the blog (`app/blog/page.js`) and blog post page (`app/blog/[slug]/page.js`). ## Creating a dynamic segment [Dynamic segments](/docs/app/api-reference/file-conventions/dynamic-routes) allow you to create routes that are generated from data. For example, instead of manually creating a route for each individual blog post, you can create a dynamic segment to generate the routes based on blog post data. To create a dynamic segment, wrap the segment (folder) name in square brackets: `[segmentName]`. For example, in the `app/blog/[slug]/page.tsx` route, the `[slug]` is the dynamic segment. ```tsx filename="app/blog/[slug]/page.tsx" switcher export default async function BlogPostPage({ params, }: { params: Promise<{ slug: string }> }) { const { slug } = await params const post = await getPost(slug) return (

{post.title}

{post.content}

) } ``` ```jsx filename="app/blog/[slug]/page.js" switcher export default async function BlogPostPage({ params }) { const { slug } = await params const post = await getPost(slug) return (

{post.title}

{post.content}

) } ``` Learn more about [Dynamic Segments](/docs/app/api-reference/file-conventions/dynamic-routes) and the [`params`](/docs/app/api-reference/file-conventions/page#params-optional) props. Nested [layouts within Dynamic Segments](/docs/app/api-reference/file-conventions/layout#params-optional) can also access the `params` props. ## Rendering with search params In a Server Component **page**, you can access search parameters using the [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) prop: ```tsx filename="app/page.tsx" switcher export default async function Page({ searchParams, }: { searchParams: Promise<{ [key: string]: string | string[] | undefined }> }) { const filters = (await searchParams).filters } ``` ```jsx filename="app/page.jsx" switcher export default async function Page({ searchParams }) { const filters = (await searchParams).filters } ``` Using `searchParams` opts your page into [**dynamic rendering**](/docs/app/glossary#dynamic-rendering) because it requires an incoming request to read the search parameters from. Client Components can read search params using the [`useSearchParams`](/docs/app/api-reference/functions/use-search-params) hook. Learn more about `useSearchParams` in [prerendered](/docs/app/api-reference/functions/use-search-params#prerendering) and [dynamically rendered](/docs/app/api-reference/functions/use-search-params#dynamic-rendering) routes. ### What to use and when - Use the `searchParams` prop when you need search parameters to **load data for the page** (e.g. pagination, filtering from a database). - Use `useSearchParams` when search parameters are used **only on the client** (e.g. filtering a list already loaded via props). - As a small optimization, you can use `new URLSearchParams(window.location.search)` in **callbacks or event handlers** to read search params without triggering re-renders. ## Linking between pages You can use the [`` component](/docs/app/api-reference/components/link) to navigate between routes. `` is a built-in Next.js component that extends the HTML `` tag to provide [prefetching](/docs/app/getting-started/linking-and-navigating#prefetching) and [client-side navigation](/docs/app/getting-started/linking-and-navigating#client-side-transitions). For example, to generate a list of blog posts, import `` from `next/link` and pass a `href` prop to the component: ```tsx filename="app/ui/post.tsx" highlight={1,2,11} switcher import Link from 'next/link' import { getPosts } from '@/lib/posts' export default async function Posts() { const posts = await getPosts() return (
    {posts.map((post) => (
  • {post.title}
    • ))}
) } ``` ```jsx filename="app/ui/post.js" highlight={1,2,11} switcher import Link from 'next/link' import { getPosts } from '@/lib/posts' export default async function Posts() { const posts = await getPosts() return (
    {posts.map((post) => (
  • {post.title}
    • ))}
) } ``` > **Good to know**: `` is the primary way to navigate between routes in Next.js. You can also use the [`useRouter` hook](/docs/app/api-reference/functions/use-router) for more advanced navigation. ## Route Props Helpers Next.js exposes utility types that infer `params` and named slots from your route structure: - [**PageProps**](/docs/app/api-reference/file-conventions/page#page-props-helper): Props for `page` components, including `params` and `searchParams`. - [**LayoutProps**](/docs/app/api-reference/file-conventions/layout#layout-props-helper): Props for `layout` components, including `children` and any named slots (e.g. folders like `@analytics`). These are globally available helpers, generated when running either `next dev`, `next build` or [`next typegen`](/docs/app/api-reference/cli/next#next-typegen-options). ```tsx filename="app/blog/[slug]/page.tsx" export default async function Page(props: PageProps<'/blog/[slug]'>) { const { slug } = await props.params return

Blog post: {slug}

} ``` ```tsx filename="app/dashboard/layout.tsx" export default function Layout(props: LayoutProps<'/dashboard'>) { return (
{props.children} {/* If you have app/dashboard/@analytics, it appears as a typed slot: */} {/* {props.analytics} */}
) } ``` > **Good to know** > > - Static routes resolve `params` to `{}`. > - `PageProps`, `LayoutProps` are global helpers — no imports required. > - Types are generated during `next dev`, `next build` or `next typegen`. --- ### 01 App 01 Getting Started 04 Linking And Navigating (`docs/01-app/01-getting-started/04-linking-and-navigating.mdx`) --- title: Linking and Navigating description: Learn how the built-in navigation optimizations work, including prefetching, prerendering, and client-side navigation, and how to optimize navigation for dynamic routes and slow networks. related: links: - app/api-reference/components/link - app/api-reference/file-conventions/loading - app/guides/optimizing-prefetching - app/guides/prefetching --- In Next.js, routes are rendered on the server by default. This often means the client has to wait for a server response before a new route can be shown. Next.js comes with built-in [prefetching](#prefetching), [streaming](#streaming), and [client-side transitions](#client-side-transitions) ensuring navigation stays fast and responsive. This guide explains how navigation works in Next.js and how you can optimize it for [dynamic routes](#dynamic-routes-without-loadingtsx) and [slow networks](#slow-networks). ## How navigation works To understand how navigation works in Next.js, it helps to be familiar with the following concepts: - [Server Rendering](#server-rendering) - [Prefetching](#prefetching) - [Streaming](#streaming) - [Client-side transitions](#client-side-transitions) ### Server Rendering In Next.js, [Layouts and Pages](/docs/app/getting-started/layouts-and-pages) are [React Server Components](https://react.dev/reference/rsc/server-components) by default. On initial and subsequent navigations, the [Server Component Payload](/docs/app/getting-started/server-and-client-components#how-do-server-and-client-components-work-in-nextjs) is generated on the server before being sent to the client. There are two types of server rendering, based on _when_ it happens: - **Prerendering** happens at build time or during [revalidation](/docs/app/getting-started/revalidating) and the result is cached. - **Dynamic Rendering** happens at request time in response to a client request. The trade-off of server rendering is that the client must wait for the server to respond before the new route can be shown. Next.js addresses this delay by [prefetching](#prefetching) routes the user is likely to visit and performing [client-side transitions](#client-side-transitions). > **Good to know**: HTML is also generated for the initial visit. ### Prefetching Prefetching is the process of loading a route in the background before the user navigates to it. This makes navigation between routes in your application feel instant, because by the time a user clicks on a link, the data to render the next route is already available client side. Next.js automatically prefetches routes linked with the [`` component](/docs/app/api-reference/components/link) when they enter the user's viewport. ```tsx filename="app/layout.tsx" switcher import Link from 'next/link' export default function Layout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` ```jsx filename="app/layout.js" switcher import Link from 'next/link' export default function Layout({ children }) { return ( {children} ) } ``` How much of the route is prefetched depends on whether it's static or dynamic: - **Static Route**: the full route is prefetched. - **Dynamic Route**: prefetching is skipped, or the route is partially prefetched if [`loading.tsx`](/docs/app/api-reference/file-conventions/loading) is present. By skipping or partially prefetching dynamic routes, Next.js avoids unnecessary work on the server for routes the users may never visit. However, waiting for a server response before navigation can give the users the impression that the app is not responding. Server Rendering without Streaming > **Good to know:** See the [Prefetching guide](/docs/app/guides/prefetching) for the full behavior, including how to control prefetching per link and how it changes when you adopt [Partial Prefetching](/docs/app/guides/adopting-partial-prefetching). To include URL-dependent content in a link's prefetch, see [Optimizing prefetching](/docs/app/guides/optimizing-prefetching). To improve the navigation experience to dynamic routes, you can use [streaming](#streaming). ### Streaming Streaming allows the server to send parts of a dynamic route to the client as soon as they're ready, rather than waiting for the entire route to be rendered. This means users see something sooner, even if parts of the page are still loading. See the [Streaming guide](/docs/app/guides/streaming) for a deep dive into how streaming works in Next.js. For dynamic routes, it means they can be **partially prefetched**. That is, shared layouts and loading skeletons can be requested ahead of time. How Server Rendering with Streaming Works To use streaming, create a `loading.tsx` in your route folder: loading.js special file ```tsx filename="app/dashboard/loading.tsx" switcher export default function Loading() { // Add fallback UI that will be shown while the route is loading. return } ``` ```jsx filename="app/dashboard/loading.js" switcher export default function Loading() { // Add fallback UI that will be shown while the route is loading. return } ``` Behind the scenes, Next.js will automatically wrap the `page.tsx` contents in a `` boundary. The prefetched fallback UI will be shown while the route is loading, and swapped for the actual content once ready. > **Good to know**: You can also use [``](https://react.dev/reference/react/Suspense) to create loading UI for nested components. Benefits of `loading.tsx`: - Immediate navigation and visual feedback for the user. - Shared layouts remain interactive and navigation is interruptible. - Improved Core Web Vitals: [TTFB](https://web.dev/articles/ttfb), [FCP](https://web.dev/articles/fcp), and [TTI](https://web.dev/articles/tti). To further improve the navigation experience, Next.js performs a [client-side transition](#client-side-transitions) with the `` component. ### Client-side transitions Traditionally, navigation to a server-rendered page triggers a full page load. This clears state, resets scroll position, and blocks interactivity. Next.js avoids this with client-side transitions using the `` component. Instead of reloading the page, it updates the content dynamically by: - Keeping any shared layouts and UI. - Replacing the current page with the prefetched loading state or a new page if available. Client-side transitions make server-rendered apps _feel_ like client-rendered apps. And when paired with [prefetching](#prefetching) and [streaming](#streaming), they enable fast transitions, even for dynamic routes. Next.js also handles [scrolling to the top of the page](/docs/app/api-reference/components/link#scroll) during client-side transitions. If content scrolls behind a sticky or fixed header after navigation, you can fix this with CSS [`scroll-padding-top`](/docs/app/api-reference/components/link#scroll-offset-with-sticky-headers). ## What can make transitions slow? These Next.js optimizations make navigation fast and responsive. However, under certain conditions, transitions can still _feel_ slow. Here are some common causes and how to improve the user experience: ### Dynamic routes without `loading.tsx` When navigating to a dynamic route, the client must wait for the server response before showing the result. This can give the users the impression that the app is not responding. We recommend adding `loading.tsx` to dynamic routes to enable partial prefetching, trigger immediate navigation, and display a loading UI while the route renders. ```tsx filename="app/blog/[slug]/loading.tsx" switcher export default function Loading() { return } ``` ```jsx filename="app/blog/[slug]/loading.js" switcher export default function Loading() { return } ``` > **Good to know**: In development mode, you can use the Next.js Devtools to identify if the route is static or dynamic. See [`devIndicators`](/docs/app/api-reference/config/next-config-js/devIndicators) for more information. ### Dynamic segments without `generateStaticParams` If a [dynamic segment](/docs/app/api-reference/file-conventions/dynamic-routes) could be prerendered but isn't because it's missing [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params), the route will fallback to dynamic rendering at request time. Ensure the route is statically generated at build time by adding `generateStaticParams`: ```tsx filename="app/blog/[slug]/page.tsx" switcher export async function generateStaticParams() { const posts = await fetch('https://.../posts').then((res) => res.json()) return posts.map((post) => ({ slug: post.slug, })) } export default async function Page({ params, }: { params: Promise<{ slug: string }> }) { const { slug } = await params // ... } ``` ```jsx filename="app/blog/[slug]/page.js" switcher export async function generateStaticParams() { const posts = await fetch('https://.../posts').then((res) => res.json()) return posts.map((post) => ({ slug: post.slug, })) } export default async function Page({ params }) { const { slug } = await params // ... } ``` ### Slow networks On slow or unstable networks, prefetching may not finish before the user clicks a link. This can affect both static and dynamic routes. In these cases, the `loading.js` fallback may not appear immediately because it hasn't been prefetched yet. To improve perceived performance, you can use the [`useLinkStatus` hook](/docs/app/api-reference/functions/use-link-status) to show immediate feedback while the transition is in progress. ```tsx filename="app/ui/loading-indicator.tsx" switcher 'use client' import { useLinkStatus } from 'next/link' export default function LoadingIndicator() { const { pending } = useLinkStatus() return ( ) } ``` ```jsx filename="app/ui/loading-indicator.js" switcher 'use client' import { useLinkStatus } from 'next/link' export default function LoadingIndicator() { const { pending } = useLinkStatus() return ( ) } ``` You can "debounce" the hint by adding an initial animation delay (e.g. 100ms) and starting as invisible (e.g. `opacity: 0`). This means the loading indicator will only be shown if the navigation takes longer than the specified delay. See the [`useLinkStatus` reference](/docs/app/api-reference/functions/use-link-status#gracefully-handling-fast-navigation) for a CSS example. > **Good to know**: An **experimental** [`useOffline`](/docs/app/api-reference/config/next-config-js/useOffline) hook can keep prefetched routes navigable during connectivity drops. See the [offline support guide](/docs/app/guides/offline-support). > **Good to know**: You can use other visual feedback patterns like a progress bar. View an example [here](https://github.com/vercel/react-transition-progress). ### Disabling prefetching You can opt out of prefetching by setting the `prefetch` prop to `false` on the `` component. This is useful to avoid unnecessary usage of resources when rendering large lists of links (e.g. an infinite scroll table). ```tsx Blog ``` However, disabling prefetching comes with trade-offs: - **Static routes** will only be fetched when the user clicks the link. - **Dynamic routes** will need to be rendered on the server first before the client can navigate to it. To reduce resource usage without fully disabling prefetch, you can prefetch only on hover. This limits prefetching to routes the user is more _likely_ to visit, rather than all links in the viewport. ```tsx filename="app/ui/hover-prefetch-link.tsx" switcher 'use client' import Link from 'next/link' import { useState } from 'react' function HoverPrefetchLink({ href, children, }: { href: string children: React.ReactNode }) { const [active, setActive] = useState(false) return ( setActive(true)} > {children} ) } ``` ```jsx filename="app/ui/hover-prefetch-link.js" switcher 'use client' import Link from 'next/link' import { useState } from 'react' function HoverPrefetchLink({ href, children }) { const [active, setActive] = useState(false) return ( setActive(true)} > {children} ) } ``` ### Hydration not completed `` is a Client Component and must be hydrated before it can prefetch routes. On the initial visit, large JavaScript bundles can delay hydration, preventing prefetching from starting right away. React mitigates this with Selective Hydration and you can further improve this by: - Using the [`@next/bundle-analyzer`](/docs/app/guides/package-bundling#nextbundle-analyzer-for-webpack) plugin to identify and reduce bundle size by removing large dependencies. - Moving logic from the client to the server where possible. See the [Server and Client Components](/docs/app/getting-started/server-and-client-components) docs for guidance. ## Examples ### Native History API Next.js allows you to use the native [`window.history.pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) and [`window.history.replaceState`](https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState) methods to update the browser's history stack without reloading the page. `pushState` and `replaceState` calls integrate into the Next.js Router, allowing you to sync with [`usePathname`](/docs/app/api-reference/functions/use-pathname) and [`useSearchParams`](/docs/app/api-reference/functions/use-search-params). #### `window.history.pushState` Use it to add a new entry to the browser's history stack. The user can navigate back to the previous state. For example, to sort a list of products: ```tsx fileName="app/ui/sort-products.tsx" switcher 'use client' import { useSearchParams } from 'next/navigation' export default function SortProducts() { const searchParams = useSearchParams() function updateSorting(sortOrder: string) { const params = new URLSearchParams(searchParams.toString()) params.set('sort', sortOrder) window.history.pushState(null, '', `?${params.toString()}`) } return ( <> ) } ``` ```jsx fileName="app/ui/sort-products.js" switcher 'use client' import { useSearchParams } from 'next/navigation' export default function SortProducts() { const searchParams = useSearchParams() function updateSorting(sortOrder) { const params = new URLSearchParams(searchParams.toString()) params.set('sort', sortOrder) window.history.pushState(null, '', `?${params.toString()}`) } return ( <> ) } ``` #### `window.history.replaceState` Use it to replace the current entry on the browser's history stack. The user is not able to navigate back to the previous state. For example, to switch the application's locale: ```tsx fileName="app/ui/locale-switcher.tsx" switcher 'use client' import { usePathname } from 'next/navigation' export function LocaleSwitcher() { const pathname = usePathname() function switchLocale(locale: string) { // e.g. '/en/about' or '/fr/contact' const newPath = `/${locale}${pathname}` window.history.replaceState(null, '', newPath) } return ( <> ) } ``` ```jsx fileName="app/ui/locale-switcher.js" switcher 'use client' import { usePathname } from 'next/navigation' export function LocaleSwitcher() { const pathname = usePathname() function switchLocale(locale) { // e.g. '/en/about' or '/fr/contact' const newPath = `/${locale}${pathname}` window.history.replaceState(null, '', newPath) } return ( <> ) } ``` --- ### 01 App 01 Getting Started 05 Server And Client Components (`docs/01-app/01-getting-started/05-server-and-client-components.mdx`) --- title: Server and Client Components description: Learn how you can use React Server and Client Components to render parts of your application on the server or the client. related: title: Next Steps description: Learn more about the APIs mentioned in this page. links: - app/api-reference/directives/use-client - app/guides/server-and-client-boundary --- By default, layouts and pages are [Server Components](https://react.dev/reference/rsc/server-components), which lets you fetch data and render parts of your UI on the server, optionally cache the result, and stream it to the client. When you need interactivity or browser APIs, you can use [Client Components](https://react.dev/reference/rsc/use-client) to layer in functionality. This page explains how Server and Client Components work in Next.js and when to use them, with examples of how to compose them together in your application. > **Good to know:** For an explanation of where each component type runs and how the boundary works, see [The Server and Client Boundary](/docs/app/guides/server-and-client-boundary). ## When to use Server and Client Components? The client and server environments have different capabilities. Server and Client Components allow you to run logic in each environment depending on your use case. Use **Client Components** when you need: - [State](https://react.dev/learn/managing-state) and [event handlers](https://react.dev/learn/responding-to-events). E.g. `onClick`, `onChange`. - [Lifecycle logic](https://react.dev/learn/lifecycle-of-reactive-effects). E.g. `useEffect`. - Browser-only APIs. E.g. `localStorage`, `window`, `navigator.geolocation`, etc. - [Custom hooks](https://react.dev/learn/reusing-logic-with-custom-hooks). Use **Server Components** when you need: - Fetch data from databases or APIs close to the source. - Use API keys, tokens, and other secrets without exposing them to the client. - Reduce the amount of JavaScript sent to the browser. - Improve the [First Contentful Paint (FCP)](https://web.dev/fcp/), and stream content progressively to the client. For example, the `` component is a Server Component that fetches data about a post, and passes it as props to the `` which handles client-side interactivity. ```tsx filename="app/[id]/page.tsx" highlight={1,17} switcher import LikeButton from '@/app/ui/like-button' import { getPost } from '@/lib/data' export default async function Page({ params, }: { params: Promise<{ id: string }> }) { const { id } = await params const post = await getPost(id) return (

{post.title}

{/* ... */}
) } ``` ```jsx filename="app/[id]/page.js" highlight={1,13} switcher import LikeButton from '@/app/ui/like-button' import { getPost } from '@/lib/data' export default async function Page({ params }) { const { id } = await params const post = await getPost(id) return (

{post.title}

{/* ... */}
) } ``` ```tsx filename="app/ui/like-button.tsx" highlight={1} switcher 'use client' import { useState } from 'react' export default function LikeButton({ likes }: { likes: number }) { // ... } ``` ```jsx filename="app/ui/like-button.js" highlight={1} switcher 'use client' import { useState } from 'react' export default function LikeButton({ likes }) { // ... } ``` ## How do Server and Client Components work in Next.js? ### On the server On the server, Next.js uses React's APIs to orchestrate rendering. The rendering work is split into chunks, by individual route segments ([layouts and pages](/docs/app/getting-started/layouts-and-pages)), including [parallel route slots](/docs/app/api-reference/file-conventions/parallel-routes) whether or not they are displayed: - **Server Components** are rendered into a special data format called the React Server Component Payload (RSC Payload). - **Client Components** and the RSC Payload are used to [prerender](/docs/app/glossary#prerendering) HTML. > **What is the React Server Component Payload (RSC)?** > > The RSC Payload is a compact, serialized representation of the rendered React Server Components tree. It's used by React on the client to update the browser's DOM. The RSC Payload contains: > > - The rendered result of Server Components > - Placeholders for where Client Components should be rendered and references to their JavaScript files > - Any props passed from a Server Component to a Client Component ### On the client (first load) Then, on the client: 1. **HTML** is used to immediately show a fast non-interactive preview of the route to the user. 2. **RSC Payload** is used to reconcile the Client and Server Component trees. 3. **JavaScript** is used to hydrate Client Components and make the application interactive. > **What is hydration?** > > Hydration is React's process for attaching [event handlers](https://react.dev/learn/responding-to-events) to the DOM, to make the static HTML interactive. ### Subsequent Navigations On subsequent navigations: - The **RSC Payload** is prefetched and cached for instant navigation. - **Client Components** are rendered entirely on the client, without the server-rendered HTML. ## Examples ### Using Client Components You can create a Client Component by adding the [`"use client"`](https://react.dev/reference/rsc/use-client) directive at the top of the file, above your imports. ```tsx filename="app/ui/counter.tsx" highlight={1} switcher 'use client' import { useState } from 'react' export default function Counter() { const [count, setCount] = useState(0) return (

{count} likes

) } ``` ```jsx filename="app/ui/counter.js" highlight={1} switcher 'use client' import { useState } from 'react' export default function Counter() { const [count, setCount] = useState(0) return (

{count} likes

) } ``` `"use client"` is used to declare a **boundary** between the Server and Client module graphs (trees). Once a file is marked with `"use client"`, **all of its imports and the components it directly renders are included in the client bundle**. This means you don’t need to add the directive to every component that is intended for the client. This behavior applies to components that are part of the Client Component’s [module graph](/docs/app/glossary#module-graph), which includes the modules it imports and the components it renders directly. It does not apply to Server Components passed as children or other props. Those components are not imported into the Client Component’s module graph. They are rendered on the server and passed to the Client Component as rendered output. See [Interleaving Server and Client Components](/docs/app/getting-started/server-and-client-components#interleaving-server-and-client-components) for how Server and Client Components can be combined. ### Reducing JS bundle size To reduce the size of your client JavaScript bundles, add `'use client'` at the top of the files that define your interactive components instead of marking large parts of your UI as Client Components. For example, the `` component contains mostly static elements like a logo and navigation links, but includes an interactive search bar. `` needs to be a Client Component, while the rest of the layout can stay a Server Component. ```tsx filename="app/layout.tsx" highlight={12} switcher // Client Component import Search from './search' // Server Component import Logo from './logo' // Layout is a Server Component by default export default function Layout({ children }: { children: React.ReactNode }) { return ( <>
{children}
) } ``` ```jsx filename="app/layout.js" highlight={12} switcher // Client Component import Search from './search' // Server Component import Logo from './logo' // Layout is a Server Component by default export default function Layout({ children }) { return ( <>
{children}
) } ``` ```tsx filename="app/ui/search.tsx" highlight={1} switcher 'use client' export default function Search() { // ... } ``` ```jsx filename="app/ui/search.js" highlight={1} switcher 'use client' export default function Search() { // ... } ``` ### Passing data from Server to Client Components You can pass data from Server Components to Client Components using props. ```tsx filename="app/[id]/page.tsx" highlight={1,12} switcher import LikeButton from '@/app/ui/like-button' import { getPost } from '@/lib/data' export default async function Page({ params, }: { params: Promise<{ id: string }> }) { const { id } = await params const post = await getPost(id) return } ``` ```jsx filename="app/[id]/page.js" highlight={1,8} switcher import LikeButton from '@/app/ui/like-button' import { getPost } from '@/lib/data' export default async function Page({ params }) { const { id } = await params const post = await getPost(id) return } ``` ```tsx filename="app/ui/like-button.tsx" highlight={1} switcher 'use client' export default function LikeButton({ likes }: { likes: number }) { // ... } ``` ```jsx filename="app/ui/like-button.js" highlight={1} switcher 'use client' export default function LikeButton({ likes }) { // ... } ``` Alternatively, you can stream data from a Server Component to a Client Component with the [`use` API](https://react.dev/reference/react/use). See an [example](/docs/app/getting-started/fetching-data#streaming-data-with-the-use-api). > **Good to know**: Props passed to Client Components need to be [serializable](https://react.dev/reference/react/use-server#serializable-parameters-and-return-values) by React. ### Interleaving Server and Client Components You can pass Server Components as a prop to a Client Component. This allows you to visually nest server-rendered UI within Client components. A common pattern is to use `children` to create a _slot_ in a ``. For example, a `` component that fetches data on the server, inside a `` component that uses client state to toggle visibility. ```tsx filename="app/ui/modal.tsx" switcher 'use client' export default function Modal({ children }: { children: React.ReactNode }) { return
{children}
} ``` ```jsx filename="app/ui/modal.js" switcher 'use client' export default function Modal({ children }) { return
{children}
} ``` Then, in a parent Server Component (e.g.``), you can pass a `` as the child of the ``: ```tsx filename="app/page.tsx" highlight={7} switcher import Modal from './ui/modal' import Cart from './ui/cart' export default function Page() { return ( ) } ``` ```jsx filename="app/page.js" highlight={7} switcher import Modal from './ui/modal' import Cart from './ui/cart' export default function Page() { return ( ) } ``` In this pattern, Server Components are rendered on the server ahead of time, even when passed as props to Client Components. The React Server Component Payload contains the rendered result of those Server Components, plus placeholders for where Client Components should be rendered and references to their JavaScript files. ### Context providers [React context](https://react.dev/learn/passing-data-deeply-with-context) is commonly used to share global state like the current theme. However, React context is not supported in Server Components. To use context, create a Client Component that accepts `children`: ```tsx filename="app/theme-provider.tsx" switcher 'use client' import { createContext } from 'react' export const ThemeContext = createContext({}) export default function ThemeProvider({ children, }: { children: React.ReactNode }) { return {children} } ``` ```jsx filename="app/theme-provider.js" switcher 'use client' import { createContext } from 'react' export const ThemeContext = createContext({}) export default function ThemeProvider({ children }) { return {children} } ``` Then, import it into a Server Component (e.g. `layout`): ```tsx filename="app/layout.tsx" switcher import ThemeProvider from './theme-provider' export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( {children} ) } ``` ```jsx filename="app/layout.js" switcher import ThemeProvider from './theme-provider' export default function RootLayout({ children }) { return ( {children} ) } ``` Your Server Component will now be able to directly render your provider, and all other Client Components throughout your app will be able to consume this context. > **Good to know**: You should render providers as deep as possible in the tree – notice how `ThemeProvider` only wraps `{children}` instead of the entire `` document. This makes it easier for Next.js to optimize the static parts of your Server Components. To pass server-fetched data through context and read it in Client Components with `use()`, see [Using React's `use` within a Context Provider](/docs/app/guides/single-page-applications#using-reacts-use-within-a-context-provider). ### Third-party components When using a third-party component that relies on client-only features, you can wrap it in a Client Component to ensure it works as expected. For example, the `` can be imported from the `acme-carousel` package. This component uses `useState`, but the module that defines it doesn't yet have the `"use client"` directive. If you use `` within a Client Component, it will work as expected: ```tsx filename="app/gallery.tsx" switcher 'use client' import { useState } from 'react' import { Carousel } from 'acme-carousel' export default function Gallery() { const [isOpen, setIsOpen] = useState(false) return (
{/* Works, since Carousel is used within a Client Component */} {isOpen && }
) } ``` ```jsx filename="app/gallery.js" switcher 'use client' import { useState } from 'react' import { Carousel } from 'acme-carousel' export default function Gallery() { const [isOpen, setIsOpen] = useState(false) return (
{/* Works, since Carousel is used within a Client Component */} {isOpen && }
) } ``` However, if you try to use it directly within a Server Component, you'll see an error. This is because Next.js doesn't know `` is using client-only features. To fix this, you can wrap third-party components that rely on client-only features in your own Client Components: ```tsx filename="app/carousel.tsx" switcher 'use client' import { Carousel } from 'acme-carousel' export default Carousel ``` ```jsx filename="app/carousel.js" switcher 'use client' import { Carousel } from 'acme-carousel' export default Carousel ``` Now, you can use `` directly within a Server Component: ```tsx filename="app/page.tsx" switcher import Carousel from './carousel' export default function Page() { return (

View pictures

{/* Works, since Carousel is a Client Component */}
) } ``` ```jsx filename="app/page.js" switcher import Carousel from './carousel' export default function Page() { return (

View pictures

{/* Works, since Carousel is a Client Component */}
) } ``` > **Advice for Library Authors** > > If you’re building a component library, add the `"use client"` directive to entry points that rely on client-only features. This lets your users import components into Server Components without needing to create wrappers. > > It's worth noting some bundlers might strip out `"use client"` directives. You can find an example of how to configure esbuild to include the `"use client"` directive in the [React Wrap Balancer](https://github.com/shuding/react-wrap-balancer/blob/main/tsup.config.ts#L10-L13) and [Vercel Analytics](https://github.com/vercel/analytics/blob/main/packages/web/tsup.config.js#L26-L30) repositories. ### Preventing environment poisoning JavaScript modules can be shared between both Server and Client Components modules. This means it's possible to accidentally import server-only code into the client. For example, consider the following function: ```ts filename="lib/data.ts" switcher export async function getData() { const res = await fetch('https://external-service.com/data', { headers: { authorization: process.env.API_KEY, }, }) return res.json() } ``` ```js filename="lib/data.js" switcher export async function getData() { const res = await fetch('https://external-service.com/data', { headers: { authorization: process.env.API_KEY, }, }) return res.json() } ``` This function contains an `API_KEY` that should never be exposed to the client. In Next.js, only environment variables prefixed with `NEXT_PUBLIC_` are included in the client bundle. If variables are not prefixed, Next.js replaces them with an empty string. As a result, even though `getData()` can be imported and executed on the client, it won't work as expected. To prevent accidental usage in Client Components, you can use the [`server-only` package](https://www.npmjs.com/package/server-only). Then, import the package into a file that contains server-only code: ```js filename="lib/data.js" import 'server-only' export async function getData() { const res = await fetch('https://external-service.com/data', { headers: { authorization: process.env.API_KEY, }, }) return res.json() } ``` Now, if you try to import the module into a Client Component, there will be a build-time error. The corresponding [`client-only` package](https://www.npmjs.com/package/client-only) can be used to mark modules that contain client-only logic like code that accesses the `window` object. In Next.js, installing `server-only` or `client-only` is **optional**. However, if your linting rules flag extraneous dependencies, you may install them to avoid issues. ```bash package="npm" npm install server-only ``` ```bash package="yarn" yarn add server-only ``` ```bash package="pnpm" pnpm add server-only ``` ```bash package="bun" bun add server-only ``` Next.js handles `server-only` and `client-only` imports internally to provide clearer error messages when a module is used in the wrong environment. The contents of these packages from NPM are not used by Next.js. Next.js also provides its own type declarations for `server-only` and `client-only`, for TypeScript configurations where [`noUncheckedSideEffectImports`](https://www.typescriptlang.org/tsconfig/#noUncheckedSideEffectImports) is active. --- ### 01 App 01 Getting Started 06 Fetching Data (`docs/01-app/01-getting-started/06-fetching-data.mdx`) --- title: Fetching Data description: Learn how to fetch data and stream content that depends on data. related: title: Next steps description: Learn more about advanced data-fetching patterns and the features mentioned in this page. links: - app/guides/single-page-applications - app/guides/data-security - app/api-reference/functions/fetch - app/api-reference/file-conventions/loading - app/api-reference/config/next-config-js/logging - app/api-reference/config/next-config-js/taint --- This page will walk you through how you can fetch data in [Server](#server-components) and [Client](#client-components) Components, and how to [stream](#streaming) components that depend on uncached data. ## Fetching data ### Server Components You can fetch data in Server Components using any asynchronous I/O, such as: 1. The [`fetch` API](#with-the-fetch-api) 2. An [ORM or database](#with-an-orm-or-database) #### With the `fetch` API To fetch data with the `fetch` API, turn your component into an asynchronous function, and await the `fetch` call. For example: ```tsx filename="app/blog/page.tsx" switcher export default async function Page() { const data = await fetch('https://api.vercel.app/blog') const posts = await data.json() return (
    {posts.map((post) => (
  • {post.title}
    • ))}
) } ``` ```jsx filename="app/blog/page.js" switcher export default async function Page() { const data = await fetch('https://api.vercel.app/blog') const posts = await data.json() return (
    {posts.map((post) => (
  • {post.title}
    • ))}
) } ``` > **Good to know:** > > - Identical `fetch` requests in a React component tree are [memoized](/docs/app/glossary#memoization) by default, so you can fetch data in the component that needs it instead of drilling props. > - `fetch` requests are not cached by default and will block the page from rendering until the request is complete. Use the [`use cache`](/docs/app/api-reference/directives/use-cache) directive to cache results, or wrap the fetching component in [``](/docs/app/getting-started/caching#streaming-uncached-data) to stream fresh data at request time. See [caching](/docs/app/getting-started/caching) for details. > - During development, you can log `fetch` calls for better visibility and debugging. See the [`logging` API reference](/docs/app/api-reference/config/next-config-js/logging). #### With an ORM or database Since Server Components are rendered on the server, credentials and query logic will not be included in the client bundle so you can safely make database queries using an ORM or database client. ```tsx filename="app/blog/page.tsx" switcher import { db, posts } from '@/lib/db' export default async function Page() { const allPosts = await db.select().from(posts) return (
    {allPosts.map((post) => (
  • {post.title}
    • ))}
) } ``` ```jsx filename="app/blog/page.js" switcher import { db, posts } from '@/lib/db' export default async function Page() { const allPosts = await db.select().from(posts) return (
    {allPosts.map((post) => (
  • {post.title}
    • ))}
) } ``` You should still ensure requests are properly authenticated and authorized. For best practices on securing server-side data access, see the [data security guide](/docs/app/guides/data-security). ### Streaming When you fetch data in Server Components, the data is fetched and rendered on the server for each request. If you have any slow data requests, the whole route will be blocked from rendering until all the data is fetched. To improve the initial load time and user experience, you can break the page into smaller _chunks_ and progressively send those chunks from the server to the client. This is called streaming. See the [Streaming guide](/docs/app/guides/streaming) for a deeper look at how streaming works, including the HTTP contract, infrastructure considerations, and performance trade-offs. How Server Rendering with Streaming Works There are two ways you can use streaming in your application: 1. Wrapping a page with a [`loading.js` file](#with-loadingjs) 2. Wrapping a component with [``](#with-suspense) > **Good to know:** Bots and crawlers are served differently from browsers. Next.js waits for data fetching to finish and sends the fully rendered page instead of streaming it progressively. See [Bots and crawlers](/docs/app/guides/streaming#bots-and-crawlers). #### With `loading.js` You can create a `loading.js` file in the same folder as your page to stream the **entire page** while the data is being fetched. For example, to stream `app/blog/page.js`, add the file inside the `app/blog` folder. Blog folder structure with loading.js file ```tsx filename="app/blog/loading.tsx" switcher export default function Loading() { // Define the Loading UI here return
Loading...
} ``` ```jsx filename="app/blog/loading.js" switcher export default function Loading() { // Define the Loading UI here return
Loading...
} ``` On navigation, the user will immediately see the layout and a [loading state](#creating-meaningful-loading-states) while the page is being rendered. The new content will then be automatically swapped in once rendering is complete. Loading UI Behind the scenes, `loading.js` will be [nested inside `layout.js`](/docs/app/getting-started/project-structure#component-hierarchy), and will automatically wrap the `page.js` file and any children below in a `` boundary. loading.js overview Because of this, a layout that accesses uncached or runtime data (e.g. `cookies()`, `headers()`, or uncached fetches) does not fall back to a same route segment `loading.js`. Instead, it blocks navigation until the layout finishes rendering. [Cache Components](/docs/app/getting-started/caching) prevents this by guiding you with a build-time error. To fix this, wrap the uncached access in its own [``](#with-suspense) boundary with a fallback, or move the data fetching into `page.js` where `loading.js` can cover it. See [`loading.js`](/docs/app/api-reference/file-conventions/loading) for more details. This is why, while `loading.js` works well for streaming route segments, using `` closer to the runtime or uncached data access is recommended. #### With `` `` allows you to be more granular about what parts of the page to stream. For example, you can immediately show any page content that falls outside of the `` boundary, and stream in the list of blog posts inside the boundary. ```tsx filename="app/blog/page.tsx" switcher import { Suspense } from 'react' import BlogList from '@/components/BlogList' import BlogListSkeleton from '@/components/BlogListSkeleton' export default function BlogPage() { return (
{/* This content will be sent to the client immediately */}

Welcome to the Blog

Read the latest posts below.

{/* If there's any dynamic content inside this boundary, it will be streamed in */} }>
) } ``` ```jsx filename="app/blog/page.js" switcher import { Suspense } from 'react' import BlogList from '@/components/BlogList' import BlogListSkeleton from '@/components/BlogListSkeleton' export default function BlogPage() { return (
{/* This content will be sent to the client immediately */}

Welcome to the Blog

Read the latest posts below.

{/* If there's any dynamic content inside this boundary, it will be streamed in */} }>
) } ``` #### Creating meaningful loading states An instant loading state is fallback UI that is shown immediately to the user after navigation. For the best user experience, we recommend designing loading states that are meaningful and help users understand the app is responding. For example, you can use skeletons and spinners, or a small but meaningful part of future screens such as a cover photo, title, etc. In development, you can preview and inspect the loading state of your components using the [React Devtools](https://react.dev/learn/react-developer-tools). ### Client Components There are two ways to fetch data in Client Components, using: 1. React's [`use` API](https://react.dev/reference/react/use) 2. A community library like [SWR](https://swr.vercel.app/) or [React Query](https://tanstack.com/query/latest) #### Streaming data with the `use` API You can use React's [`use` API](https://react.dev/reference/react/use) to [stream](#streaming) data from the server to client. Start by fetching data in your Server component, and pass the promise to your Client Component as prop: ```tsx filename="app/blog/page.tsx" switcher import Posts from '@/app/ui/posts' import { Suspense } from 'react' export default function Page() { // Don't await the data fetching function const posts = getPosts() return ( Loading...

}> ) } ``` ```jsx filename="app/blog/page.js" switcher import Posts from '@/app/ui/posts' import { Suspense } from 'react' export default function Page() { // Don't await the data fetching function const posts = getPosts() return ( Loading...}> ) } ``` Then, in your Client Component, use the `use` API to read the promise: ```tsx filename="app/ui/posts.tsx" switcher 'use client' import { use } from 'react' export default function Posts({ posts, }: { posts: Promise<{ id: string; title: string }[]> }) { const allPosts = use(posts) return (
    {allPosts.map((post) => (
  • {post.title}
    • ))}
) } ``` ```jsx filename="app/ui/posts.js" switcher 'use client' import { use } from 'react' export default function Posts({ posts }) { const allPosts = use(posts) return (
    {allPosts.map((post) => (
  • {post.title}
    • ))}
) } ``` In the example above, the `` component is wrapped in a [`` boundary](https://react.dev/reference/react/Suspense). This means the fallback will be shown while the promise is being resolved. Learn more about [streaming](#streaming). You can resolve a promise on the server with `await` or in a Client Component with `use()`. React covers [when to resolve a Promise in a Server or Client Component](https://react.dev/reference/react/use#resolve-promise-in-server-or-client-component). To share one promise with many Client Components instead of passing it as a prop, provide it through context. See [Using React's `use` within a Context Provider](/docs/app/guides/single-page-applications#using-reacts-use-within-a-context-provider). #### Community libraries You can use a community library like [SWR](https://swr.vercel.app/) or [React Query](https://tanstack.com/query/latest) to fetch data in Client Components. These libraries have their own semantics for caching, streaming, and other features. For example, with SWR: ```tsx filename="app/blog/page.tsx" switcher 'use client' import useSWR from 'swr' const fetcher = (url) => fetch(url).then((r) => r.json()) export default function BlogPage() { const { data, error, isLoading } = useSWR( 'https://api.vercel.app/blog', fetcher ) if (isLoading) return
Loading...
if (error) return
Error: {error.message}
return (
    {data.map((post: { id: string; title: string }) => (
  • {post.title}
    • ))}
) } ``` ```jsx filename="app/blog/page.js" switcher 'use client' import useSWR from 'swr' const fetcher = (url) => fetch(url).then((r) => r.json()) export default function BlogPage() { const { data, error, isLoading } = useSWR( 'https://api.vercel.app/blog', fetcher ) if (isLoading) return
Loading...
if (error) return
Error: {error.message}
return (
    {data.map((post) => (
  • {post.title}
    • ))}
) } ``` See [Client-side data fetching](/docs/app/guides/client-side-data-fetching) for direct browser fetching, providing initial data from a Server Component, and coordinating a library cache with the Next.js server and client caches. ## Examples ### Sequential data fetching Sequential data fetching happens when one request depends on data from another. For example, `` can only fetch data after `getArtist()` resolves because it needs the `artistID`: ```tsx filename="app/artist/[username]/page.tsx" switcher export default async function Page({ params, }: { params: Promise<{ username: string }> }) { const { username } = await params // Get artist information const artist = await getArtist(username) return ( <>

{artist.name}

{/* Show fallback UI while the Playlists component is loading */} Loading...}> {/* Pass the artist ID to the Playlists component */} ) } async function Playlists({ artistID }: { artistID: string }) { // Use the artist ID to fetch playlists const playlists = await getArtistPlaylists(artistID) return (
    {playlists.map((playlist) => (
  • {playlist.name}
    • ))}
) } ``` ```jsx filename="app/artist/[username]/page.js" switcher export default async function Page({ params }) { const { username } = await params // Get artist information const artist = await getArtist(username) return ( <>

{artist.name}

{/* Show fallback UI while the Playlists component is loading */} Loading...}> {/* Pass the artist ID to the Playlists component */} ) } async function Playlists({ artistID }) { // Use the artist ID to fetch playlists const playlists = await getArtistPlaylists(artistID) return (
    {playlists.map((playlist) => (
  • {playlist.name}
    • ))}
) } ``` In this example, `` allows the playlists to stream in after the artist data loads. However, the page still waits for the artist data before displaying anything. To prevent this, you can wrap the entire page component in a `` boundary (for example, using a [`loading.js` file](#with-loadingjs)) to show a loading state immediately. Ensure your data source can resolve the first request quickly, as it blocks everything else. If you can't optimize the request further, consider [caching](/docs/app/getting-started/caching) the result if the data changes infrequently. ### Parallel data fetching Parallel data fetching happens when data requests in a route are eagerly initiated and start at the same time. By default, [layouts and pages](/docs/app/getting-started/layouts-and-pages) are rendered in parallel. So each segment starts fetching data as soon as possible. However, within _any_ component, multiple `async`/`await` requests can still be sequential if placed after the other. For example, `getAlbums` will be blocked until `getArtist` is resolved: ```tsx filename="app/artist/[username]/page.tsx" switcher import { getArtist, getAlbums } from '@/app/lib/data' export default async function Page({ params }) { // These requests will be sequential const { username } = await params const artist = await getArtist(username) const albums = await getAlbums(username) return
{artist.name}
} ``` Start multiple requests by calling `fetch`, then await them with [`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all). Requests begin as soon as `fetch` is called. ```tsx filename="app/artist/[username]/page.tsx" highlight={3,8,24} switcher import Albums from './albums' async function getArtist(username: string) { const res = await fetch(`https://api.example.com/artist/${username}`) return res.json() } async function getAlbums(username: string) { const res = await fetch(`https://api.example.com/artist/${username}/albums`) return res.json() } export default async function Page({ params, }: { params: Promise<{ username: string }> }) { const { username } = await params // Initiate requests const artistData = getArtist(username) const albumsData = getAlbums(username) const [artist, albums] = await Promise.all([artistData, albumsData]) return ( <>

{artist.name}

) } ``` ```jsx filename="app/artist/[username]/page.js" highlight={3,8,20} switcher import Albums from './albums' async function getArtist(username) { const res = await fetch(`https://api.example.com/artist/${username}`) return res.json() } async function getAlbums(username) { const res = await fetch(`https://api.example.com/artist/${username}/albums`) return res.json() } export default async function Page({ params }) { const { username } = await params // Initiate requests const artistData = getArtist(username) const albumsData = getAlbums(username) const [artist, albums] = await Promise.all([artistData, albumsData]) return ( <>

{artist.name}

) } ``` > **Good to know:** If one request fails when using `Promise.all`, the entire operation will fail. To handle this, you can use the [`Promise.allSettled`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) method instead. ### Reusing data with `React.cache` For data access that does not use `fetch`, such as an ORM or database query, wrap the function in [`React.cache`](https://react.dev/reference/react/cache). Multiple components can then call the function within the same request while sharing one result: ```ts filename="app/lib/user.ts" switcher import { cache } from 'react' import { db, eq, users } from '@/lib/db' export const getUser = cache(async (id: string) => { return db.query.users.findFirst({ where: eq(users.id, id), }) }) ``` ```js filename="app/lib/user.js" switcher import { cache } from 'react' import { db, eq, users } from '@/lib/db' export const getUser = cache(async (id) => { return db.query.users.findFirst({ where: eq(users.id, id), }) }) ``` Server Components can call `getUser()` directly: ```tsx filename="app/dashboard/page.tsx" switcher import { getUser } from '../lib/user' export default async function DashboardPage() { const user = await getUser('1') if (!user) { return null } return

Dashboard for {user.name}

} ``` ```jsx filename="app/dashboard/page.js" switcher import { getUser } from '../lib/user' export default async function DashboardPage() { const user = await getUser('1') if (!user) { return null } return

Dashboard for {user.name}

} ``` Since `getUser` is wrapped with `React.cache`, calls with the same `id` within one request return the same memoized result. > **Good to know:** [`React.cache`](https://react.dev/reference/react/cache#caveats) is scoped to the current request only. Each request gets its own memoization scope with no sharing between requests. ### Preloading data When a component renders after other blocking work, its data request starts late even if the request inputs are already available. Preloading starts the request earlier so it can run in parallel with that work and avoid a request waterfall. To preload data, call the data-fetching function without `await` before blocking work, then call the same function in the component that consumes the result. The data-fetching function must deduplicate matching calls so the component can reuse the request started during preloading. Use one of the following approaches: - For `fetch`, [identical requests are memoized automatically](/docs/app/api-reference/functions/fetch#memoization). - For an ORM or database, wrap the data-fetching function in [`React.cache`](#reusing-data-with-reactcache). - With Cache Components, add [`'use cache'`](/docs/app/api-reference/directives/use-cache) to the data-fetching function. If the function reads request APIs such as `cookies()` or `headers()`, use [`'use cache: private'`](/docs/app/api-reference/directives/use-cache-private). In production, matching calls to a private Cache Function can reuse the same result within one request. This lets a component reuse a request started during preloading without storing the result in a server cache across requests. Keep the preload function next to the component that consumes the data. This makes the dependency easier to find if you move or remove the component: ```tsx filename="app/item/[id]/item.tsx" switcher async function getItem(id: string) { const res = await fetch(`https://api.example.com/items/${id}`) return res.json() } export const preload = (id: string) => { void getItem(id) } export default async function Item({ id }: { id: string }) { const item = await getItem(id) return
{item.name}
} ``` ```jsx filename="app/item/[id]/item.js" switcher async function getItem(id) { const res = await fetch(`https://api.example.com/items/${id}`) return res.json() } export const preload = (id) => { void getItem(id) } export default async function Item({ id }) { const item = await getItem(id) return
{item.name}
} ``` Call `preload()` before another blocking request to start loading the item earlier: ```tsx filename="app/item/[id]/page.tsx" switcher import Item, { preload } from './item' import { checkIsAvailable } from '@/app/lib/data' export default async function Page({ params, }: { params: Promise<{ id: string }> }) { const { id } = await params preload(id) const isAvailable = await checkIsAvailable(id) return isAvailable ? : null } ``` ```jsx filename="app/item/[id]/page.js" switcher import Item, { preload } from './item' import { checkIsAvailable } from '@/app/lib/data' export default async function Page({ params }) { const { id } = await params preload(id) const isAvailable = await checkIsAvailable(id) return isAvailable ? : null } ``` The item request continues while `checkIsAvailable()` runs. If the page renders ``, the identical `fetch` call reuses the request that `preload()` started. --- ### 01 App 01 Getting Started 07 Mutating Data (`docs/01-app/01-getting-started/07-mutating-data.mdx`) --- title: Mutating Data description: Learn how to mutate data using Server Functions and Server Actions in Next.js. related: title: Next steps description: Learn more about Server Actions and the APIs mentioned in this page. links: - app/guides/server-actions - app/api-reference/functions/revalidatePath - app/api-reference/functions/revalidateTag - app/api-reference/functions/redirect --- You can mutate data in Next.js using [React Server Functions](https://react.dev/reference/rsc/server-functions). This page will go through how you can [create](#creating-server-functions) and [invoke](#invoking-server-functions) Server Functions. For Next.js-specific behaviors (single-roundtrip response, sequential dispatch, security, deployment), see [Server Actions and Mutations](/docs/app/guides/server-actions). ## What are Server Functions? A **Server Function** is an asynchronous function that runs on the server. You can call them from the client through a network request, which is why they must be asynchronous. In an `action` or mutation context, they are also called **Server Actions**. By convention, a Server Action is an async function used with [`startTransition`](https://react.dev/reference/react/startTransition). This happens automatically when the function is: - Passed to a `
` using the `action` prop. - Passed to a ` } ``` ```jsx filename="app/ui/button.js" switcher 'use client' import { createPost } from '@/app/actions' export function Button() { return } ``` > **Good to know:** In Client Components, forms invoking Server Actions will queue submissions if JavaScript isn't loaded yet, and will be prioritized for hydration. After hydration, the browser does not refresh on form submission. ### Passing actions as props You can also pass an action to a Client Component as a prop: ```jsx ``` ```tsx filename="app/client-component.tsx" switcher 'use client' export default function ClientComponent({ updateItemAction, }: { updateItemAction: (formData: FormData) => void }) { return {/* ... */} } ``` ```jsx filename="app/client-component.js" switcher 'use client' export default function ClientComponent({ updateItemAction }) { return
{/* ... */}
} ``` ## Invoking Server Functions There are two main ways you can invoke a Server Function: 1. [Forms](#forms) in Server and Client Components 2. [Event Handlers](#event-handlers) and [useEffect](#useeffect) in Client Components > **Good to know:** Server Functions are designed for server-side mutations. The client currently dispatches and awaits them one at a time. This is an implementation detail and may change. If you need parallel data fetching, use [data fetching](/docs/app/getting-started/fetching-data#server-components) in Server Components, or perform parallel work inside a single Server Function or [Route Handler](/docs/app/guides/backend-for-frontend#manipulating-data). ### Forms React extends the HTML [`
`](https://react.dev/reference/react-dom/components/form) element to allow a Server Function to be invoked with the HTML `action` prop. When invoked in a form, the function automatically receives the [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData/FormData) object. You can extract the data using the native [`FormData` methods](https://developer.mozilla.org/en-US/docs/Web/API/FormData#instance_methods): ```tsx filename="app/ui/form.tsx" switcher import { createPost } from '@/app/actions' export function Form() { return (
) } ``` ```jsx filename="app/ui/form.js" switcher import { createPost } from '@/app/actions' export function Form() { return (
) } ``` ```ts filename="app/actions.ts" switcher 'use server' import { auth } from '@/lib/auth' export async function createPost(formData: FormData) { const session = await auth() if (!session?.user) { throw new Error('Unauthorized') } const title = formData.get('title') const content = formData.get('content') // Mutate data // Revalidate cache } ``` ```js filename="app/actions.js" switcher 'use server' import { auth } from '@/lib/auth' export async function createPost(formData) { const session = await auth() if (!session?.user) { throw new Error('Unauthorized') } const title = formData.get('title') const content = formData.get('content') // Mutate data // Revalidate cache } ``` ### Event Handlers You can invoke a Server Function in a Client Component by using event handlers such as `onClick`. ```tsx filename="app/like-button.tsx" switcher 'use client' import { incrementLike } from './actions' import { useState } from 'react' export default function LikeButton({ initialLikes }: { initialLikes: number }) { const [likes, setLikes] = useState(initialLikes) return ( <>

Total Likes: {likes}

) } ``` ```jsx filename="app/like-button.js" switcher 'use client' import { incrementLike } from './actions' import { useState } from 'react' export default function LikeButton({ initialLikes }) { const [likes, setLikes] = useState(initialLikes) return ( <>

Total Likes: {likes}

) } ``` ## Examples ### Showing a pending state While executing a Server Function, you can show a loading indicator with React's [`useActionState`](https://react.dev/reference/react/useActionState) hook. This hook returns a `pending` boolean: ```tsx filename="app/ui/button.tsx" switcher 'use client' import { useActionState, startTransition } from 'react' import { createPost } from '@/app/actions' import { LoadingSpinner } from '@/app/ui/loading-spinner' export function Button() { const [state, action, pending] = useActionState(createPost, false) return ( ) } ``` ```jsx filename="app/ui/button.js" switcher 'use client' import { useActionState, startTransition } from 'react' import { createPost } from '@/app/actions' import { LoadingSpinner } from '@/app/ui/loading-spinner' export function Button() { const [state, action, pending] = useActionState(createPost, false) return ( ) } ``` See the [Building interactive apps](/docs/app/guides/interactive-apps) guide for a deeper walkthrough of responsive interactions, including pending feedback, optimistic UI, transitions, and error handling. > **Good to know**: With the **experimental** [`useOffline`](/docs/app/guides/offline-support) config enabled, a Server Action interrupted by a connectivity drop stays pending and completes when the network returns. ### Refresh data After a mutation, you may want to refresh the current page to show the latest data. You can do this by calling [`refresh`](/docs/app/api-reference/functions/refresh) from `next/cache` in a Server Action: ```ts filename="app/lib/actions.ts" switcher 'use server' import { auth } from '@/lib/auth' import { refresh } from 'next/cache' export async function updatePost(formData: FormData) { const session = await auth() if (!session?.user) { throw new Error('Unauthorized') } // Mutate data // ... refresh() } ``` ```js filename="app/lib/actions.js" switcher 'use server' import { auth } from '@/lib/auth' import { refresh } from 'next/cache' export async function updatePost(formData) { const session = await auth() if (!session?.user) { throw new Error('Unauthorized') } // Mutate data // ... refresh() } ``` This refreshes the client router, ensuring the UI reflects the latest state. The `refresh()` function does not revalidate tagged data. To revalidate tagged data, use [`updateTag`](/docs/app/api-reference/functions/updateTag) or [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) instead. ### Revalidate data After performing a mutation, you can revalidate the Next.js cache and show the updated data by calling [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) or [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) within the Server Function: ```ts filename="app/lib/actions.ts" switcher import { auth } from '@/lib/auth' import { revalidatePath } from 'next/cache' export async function createPost(formData: FormData) { 'use server' const session = await auth() if (!session?.user) { throw new Error('Unauthorized') } // Mutate data // ... revalidatePath('/posts') } ``` ```js filename="app/lib/actions.js" switcher import { auth } from '@/lib/auth' import { revalidatePath } from 'next/cache' export async function createPost(formData) { 'use server' const session = await auth() if (!session?.user) { throw new Error('Unauthorized') } // Mutate data // ... revalidatePath('/posts') } ``` ### Redirect after a mutation You may want to redirect the user to a different page after a mutation. You can do this by calling [`redirect`](/docs/app/api-reference/functions/redirect) within the Server Function. ```ts filename="app/lib/actions.ts" switcher 'use server' import { auth } from '@/lib/auth' import { revalidatePath } from 'next/cache' import { redirect } from 'next/navigation' export async function createPost(formData: FormData) { const session = await auth() if (!session?.user) { throw new Error('Unauthorized') } // Mutate data // ... revalidatePath('/posts') redirect('/posts') } ``` ```js filename="app/lib/actions.js" switcher 'use server' import { auth } from '@/lib/auth' import { revalidatePath } from 'next/cache' import { redirect } from 'next/navigation' export async function createPost(formData) { const session = await auth() if (!session?.user) { throw new Error('Unauthorized') } // Mutate data // ... revalidatePath('/posts') redirect('/posts') } ``` Calling `redirect` [throws](/docs/app/api-reference/functions/redirect#behavior) a framework handled control-flow exception. Any code after it won't execute. If you need fresh data, call [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) or [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) beforehand. ### Cookies You can `get`, `set`, and `delete` cookies inside a Server Action using the [`cookies`](/docs/app/api-reference/functions/cookies) API. When you [set or delete](/docs/app/api-reference/functions/cookies#understanding-cookie-behavior-in-server-functions) a cookie in a Server Action, Next.js re-renders the current page and its layouts on the server so the **UI reflects the new cookie value**. > **Good to know**: The server update applies to the current React tree, re-rendering, mounting, or unmounting components, as needed. Client state is preserved for re-rendered components, and effects re-run if their dependencies changed. ```ts filename="app/actions.ts" switcher 'use server' import { cookies } from 'next/headers' export async function exampleAction() { const cookieStore = await cookies() // Get cookie cookieStore.get('name')?.value // Set cookie cookieStore.set('name', 'Delba') // Delete cookie cookieStore.delete('name') } ``` ```js filename="app/actions.js" switcher 'use server' import { cookies } from 'next/headers' export async function exampleAction() { // Get cookie const cookieStore = await cookies() // Get cookie cookieStore.get('name')?.value // Set cookie cookieStore.set('name', 'Delba') // Delete cookie cookieStore.delete('name') } ``` ### useEffect You can use the React [`useEffect`](https://react.dev/reference/react/useEffect) hook to invoke a Server Action when the component mounts or a dependency changes. This is useful for mutations that depend on global events or need to be triggered automatically. For example, `onKeyDown` for app shortcuts, an intersection observer hook for infinite scrolling, or when the component mounts to update a view count: ```tsx filename="app/view-count.tsx" switcher 'use client' import { incrementViews } from './actions' import { useState, useEffect, useTransition } from 'react' export default function ViewCount({ initialViews }: { initialViews: number }) { const [views, setViews] = useState(initialViews) const [isPending, startTransition] = useTransition() useEffect(() => { startTransition(async () => { const updatedViews = await incrementViews() setViews(updatedViews) }) }, []) // You can use `isPending` to give users feedback return

Total Views: {views}

} ``` ```jsx filename="app/view-count.js" switcher 'use client' import { incrementViews } from './actions' import { useState, useEffect, useTransition } from 'react' export default function ViewCount({ initialViews }) { const [views, setViews] = useState(initialViews) const [isPending, startTransition] = useTransition() useEffect(() => { startTransition(async () => { const updatedViews = await incrementViews() setViews(updatedViews) }) }, []) // You can use `isPending` to give users feedback return

Total Views: {views}

} ``` --- ### 01 App 01 Getting Started 08 Caching (`docs/01-app/01-getting-started/08-caching.mdx`) --- title: Caching description: Learn how to cache data and UI in Next.js related: title: Next Steps description: Learn more about revalidation and the APIs mentioned on this page. links: - app/getting-started/revalidating - app/api-reference/directives/use-cache - app/api-reference/config/next-config-js/cacheComponents - app/guides/instant-navigation --- > This page covers caching with [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents), enabled by setting [`cacheComponents: true`](/docs/app/api-reference/config/next-config-js/cacheComponents) in your `next.config.ts` file. If you'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. ## Enabling Cache Components New App Router apps created with the recommended [`create-next-app`](/docs/app/api-reference/cli/create-next-app) defaults already have Cache Components and Partial Prefetching enabled. To enable it in an existing or manually created app, add the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) and [`partialPrefetching`](/docs/app/api-reference/config/next-config-js/partialPrefetching) options to your Next config file: ```ts filename="next.config.ts" switcher import type { NextConfig } from 'next' const nextConfig: NextConfig = { cacheComponents: true, partialPrefetching: true, } export default nextConfig ``` ```js filename="next.config.js" switcher /** @type {import('next').NextConfig} */ const nextConfig = { cacheComponents: true, partialPrefetching: true, } module.exports = nextConfig ``` Set `partialPrefetching` explicitly. Leaving it unset logs a warning, because the first release of Cache Components did not include Partial Prefetching. Set it to `false` only while [migrating an app that adopted Cache Components before Partial Prefetching](/docs/app/guides/adopting-partial-prefetching). Both features will be enabled everywhere in the next major release, and the options will be removed. > **Good to know:** When Cache Components is enabled, `GET` Route Handlers follow the same prerendering model as pages. See [Route Handlers with Cache Components](/docs/app/getting-started/route-handlers#with-cache-components) for details. ## Usage The [`use cache`](/docs/app/api-reference/directives/use-cache) directive caches the return value of async functions and components. You can apply it at two levels: - **Data-level**: Cache a function that fetches or computes data (e.g., `getProducts()`, `getUser(id)`) - **UI-level**: Cache an entire component or page (e.g., `async function BlogPosts()`) A cache directive gives a result a lifetime, which Next.js uses for time-based revalidation and rendering optimizations. For on-demand revalidation after a mutation, see [Revalidating](/docs/app/getting-started/revalidating). See [Prerendering](#prerendering) for how cached results become part of the static shell and may be included in a [prefetch](#prefetching). > **Good to know:** We recommend pairing every cache directive with a [`cacheLife`](/docs/app/api-reference/functions/cacheLife). Without one, the implicit `default` profile applies. Arguments and any values captured from parent scopes automatically become part of the [cache key](/docs/app/api-reference/directives/use-cache#cache-keys), which means different inputs will produce separate cache entries. See [cache output](/docs/app/api-reference/directives/use-cache#cache-output) for what an entry holds, and [serialization requirements and constraints](/docs/app/api-reference/directives/use-cache#constraints) for details on what can be cached and how arguments work. ### Data-level caching To cache an asynchronous function that fetches data, add the `use cache` directive at the top of the function body: ```tsx filename="app/lib/data.ts" highlight={1,4,5} import { cacheLife } from 'next/cache' export async function getUsers() { 'use cache' cacheLife('hours') return db.query('SELECT * FROM users') } ``` Data-level caching is useful when the same data is used across multiple components, or when you want to cache the data independently from the UI. ### UI-level caching To cache an entire component, page, or layout, add the `use cache` directive at the top of the component or page body: ```tsx filename="app/page.tsx" highlight={1,4,5} import { cacheLife } from 'next/cache' export default async function Page() { 'use cache' cacheLife('hours') const users = await db.query('SELECT * FROM users') return (
    {users.map((user) => (
  • {user.name}
    • ))}
) } ``` > If you add "`use cache`" at the top of a file, all exported functions in the file will be cached. ### Streaming uncached data For components that fetch data from an asynchronous source such as an API, a database, or any other async operation, and require fresh data on every request, do not use `"use cache"`. Instead, wrap the component in [``](https://react.dev/reference/react/Suspense) and provide a fallback UI. The fallback ships with the prerendered shell while the async work runs at request time. ```tsx filename="page.tsx" import { Suspense } from 'react' async function LatestPosts() { const data = await fetch('https://api.example.com/posts') const posts = await data.json() return (
    {posts.map((post) => (
  • {post.title}
    • ))}
) } export default function Page() { return ( <>

My Blog

Loading posts...

}> ) } ``` For example, `

Loading posts...

` is included in the static shell, and the posts stream in at request time. Without a `` boundary around the uncached read, the dev overlay surfaces the **blocking-route** insight with this fix: ', highlight: true }, { text: ' ' }, { text: '', highlight: true }, ]} /> > **Good to know:** Each fix card links to a detailed walkthrough with patterns, code samples, and trade-offs. Click a card to dive in. {/* xref to the sync io section - that section should also emphasize that these are not random or timestamp sync invocations, in the referenced section */} `` provides a fallback UI while async work completes, but it does not itself opt a component into dynamic rendering. If a component only performs synchronous work, it will complete during prerendering regardless of whether it is wrapped in ``. ## Working with runtime APIs Runtime APIs require information that is only available when a user makes a request. These include: - [`cookies`](/docs/app/api-reference/functions/cookies) - User's cookie data - [`headers`](/docs/app/api-reference/functions/headers) - Request headers - [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) - URL query parameters - [`params`](/docs/app/api-reference/file-conventions/page#params-optional) - Dynamic route parameters. Use [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) to prerender specific values at build time, or [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) to serve an [App Shell](/docs/app/glossary#app-shell) while unknown params resolve in the background. Components that access runtime APIs should be wrapped in ``: ```tsx filename="page.tsx" import { cookies } from 'next/headers' import { Suspense } from 'react' async function UserGreeting() { const cookieStore = await cookies() const theme = cookieStore.get('theme')?.value || 'light' return

Your theme: {theme}

} export default function Page() { return ( <>

Dashboard

Loading...

}> ) } ``` A runtime API access without `` surfaces the same **blocking-route** insight in the dev overlay, with the same fix: ', highlight: true }, { text: ' ' }, { text: '', highlight: true }, ]} /> Runtime-dependent data can still be given a cache lifetime with [`"use cache: private"`](/docs/app/api-reference/directives/use-cache-private), another variant that ships with Cache Components. It gives a lifetime to a function that reads cookies, headers, or `searchParams` directly, so it can be included in a [prefetch](#prefetching). The following section shows an alternative to `use cache: private`: extracting a runtime value and passing it to a shared cached function. ### Passing runtime values to cached functions You can extract values from runtime APIs and pass them as arguments to cached functions: ```tsx filename="app/profile/page.tsx" import { cookies } from 'next/headers' import { Suspense } from 'react' export default function Page() { return ( Loading...}> ) } // Component (not cached) reads runtime data async function ProfileContent() { const session = (await cookies()).get('session')?.value return } // Cached component receives extracted value as a prop async function CachedContent({ sessionId }: { sessionId: string }) { 'use cache' // sessionId becomes part of the cache key const data = await fetchUserData(sessionId) return
{data}
} ``` At request time, `` executes if no matching cache entry is found, and stores the result for future requests with the same `sessionId`. > **Good to know:** Because `` is gated behind request data, it isn't added to the prerendered static shell. At runtime it's cached [in-memory](/docs/app/api-reference/directives/use-cache#runtime-caching-considerations) by default, which doesn't persist across serverless requests, so it may re-evaluate on each request. Reach for [`'use cache: remote'`](/docs/app/api-reference/directives/use-cache-remote) for durable, shared caching. With this pattern, [prefetching](#prefetching) can prerender `` with the user's actual session during a client transition and have the result ready before the click. This works even when server-side entries rarely survive between requests, because the lifetime you assign is what lets the result join the prefetch, where the client treats it as fresh for its [`cacheLife`](/docs/app/api-reference/functions/cacheLife) `stale` window. ## Static, cached, and streaming Here's a complete example showing static content, cached dynamic content, and streaming dynamic content working together on a single page: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` During prerendering, the header (static) and blog posts (cached with `use cache`) become part of the static shell, along with the fallback UI for user preferences. The UI preferences stored in cookies stream in at request time. Reading `cookies()` here doesn't opt-in the whole route into dynamic rendering, the way the previous rendering model did. The Suspense boundary provides fallback UI where the runtime access streams, while static and cached content still ship in the initial HTML. Just as `` contains async access, an **error boundary** contains failures: wrap them around a subtree that might error during rendering. Use [`catchError`](/docs/app/api-reference/functions/catchError) for component-level boundaries, or the [`error.js`](/docs/app/api-reference/file-conventions/error) file convention for route-level boundaries. As you build, consider that inside [`generateMetadata`](/docs/app/api-reference/functions/generate-metadata#with-cache-components) and [`generateViewport`](/docs/app/api-reference/functions/generate-viewport#with-cache-components), uncached fetches or runtime data access surface the same insights and errors as in your page, guiding you to the rendering you intend. For incremental static regeneration with both known and unknown param values, see [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components). ## Random values and timestamps Operations like `Math.random()`, `Date.now()`, or `crypto.randomUUID()` produce different values each time they execute. Cache Components requires you to explicitly handle these. > **Good to know:** `performance.now()` is meant for telemetry, so Next.js doesn't treat it as a value to guard. Use it for timing and pass the result to your logger or metrics rather than rendering it. **To generate unique values per request**, defer to request time by calling [`connection()`](/docs/app/api-reference/functions/connection) before these operations, and wrap the component in ``: ```tsx filename="page.tsx" highlight={1,4-6} import { connection } from 'next/server' import { Suspense } from 'react' async function UniqueContent() { await connection() const uuid = crypto.randomUUID() return

Request ID: {uuid}

} export default function Page() { return ( Loading...

}> ) } ``` Alternatively, you can **cache the result** so all users see the same value until revalidation: ```tsx filename="page.tsx" export default async function Page() { 'use cache' const buildId = crypto.randomUUID() return

Build ID: {buildId}

} ``` You don't need to memorize which operations behave this way. The dev overlay surfaces a **blocking-prerender-random**, **blocking-prerender-current-time**, or **blocking-prerender-crypto** insight (depending on the call) with these fixes: ' }, ]} /> ## Predictable values Unlike random values and timestamps, which can vary between renders, module imports, synchronous I/O, and pure computations produce the same result every time they run. Components using only these operations are prerendered automatically, and their output becomes part of the static HTML at build time. ```tsx filename="page.tsx" import fs from 'node:fs' export default async function Page() { const constants = await import('./constants.json') const content = fs.readFileSync('./config.json', 'utf-8') const items = JSON.parse(content).items ?? [] return (

{constants.appName}

    {items.map((item) => (
  • {item.value}
    • ))}
) } ``` > **Good to know:** This includes queries to embedded databases with synchronous APIs, such as `better-sqlite3` or Node.js's built-in [`node:sqlite`](https://nodejs.org/api/sqlite.html). If you need per-request data from a synchronous source, call [`connection()`](/docs/app/api-reference/functions/connection) before the query. Some asynchronous APIs read local resources that don't depend on the incoming request, such as fonts or configuration files. When those resources are expected to be the same for every request, read them once at module scope instead of during rendering If the data should instead be computed during rendering and reused across requests, wrap the read in [`use cache`](/docs/app/api-reference/directives/use-cache). If the data depends on the incoming request or is expected to change over time, read it during request-time rendering. ```tsx filename="page.tsx" import { readFile } from 'node:fs/promises' const content = await readFile('./config.json', 'utf-8') const items = JSON.parse(content).items ?? [] export default function Page() { return (
    {items.map((item) => (
  • {item.value}
    • ))}
) } ``` In this example, the configuration file is expected to be the same for every request, so it is read once at module scope. Calling `await readFile()` inside the component would be treated as uncached data that must be either accessed within `use cache` or behind a `` boundary. Since this file does not depend on the request and is not expected to change, module scope is the simplest option. ## Prerendering At build time, Next.js renders your route's component tree. How each component is handled depends on the APIs it uses: - [`use cache`](#usage): the result is cached and included in the static shell, as long as its lifetime [isn't too short](/docs/app/api-reference/functions/cacheLife#prerendering-behavior) - [``](#streaming-uncached-data): fallback UI is included in the static shell while the content streams at request time - [Predictable values](#predictable-values): module imports, `fs.readFileSync`, and pure computations complete during prerender and are included in the static shell automatically - [Random values and timestamps](#random-values-and-timestamps): use `connection()` + `` to get a unique value per request, or `use cache` to share one across users This generates a static shell consisting of HTML for initial page loads and a serialized [RSC Payload](/docs/app/getting-started/server-and-client-components#on-the-server) for client-side navigation, ensuring the browser receives fully rendered content instantly whether users navigate directly to the URL or transition from another page. This rendering approach is called **Partial Prerendering (PPR)**, the default behavior with Cache Components. Partially re-rendered Product Page showing static nav and product information, and dynamic cart and recommended products Every produced static shell can be served directly from a CDN, without going through to the upstream server. This makes direct navigations [instant](#instant-navigation). What ends up in a route's static shell depends on what's known at build time. When a route's [dynamic params](/docs/app/api-reference/functions/generate-static-params) are known, the shell contains that concrete content, and any remaining uncached or runtime data still streams behind its `` fallback. When the params aren't known, the reusable, URL-independent version is the [**App Shell**](/docs/app/glossary#app-shell): the same static shell with the param-specific parts left behind their fallbacks. [Incremental Static Regeneration](#incremental-static-regeneration) fills in the concrete versions after the first visit. Next.js requires you to explicitly handle components that can't complete during prerendering. It surfaces a validation insight in the dev overlay and dev server console that names the route and points at fixes (cache the access, move it into a `` boundary, or opt the route out). This validation keeps every route producing a static shell, so direct navigations stay instant. Diagram showing partially rendered page on the client, with loading UI for chunks that are being streamed. > **🎥 Watch:** Why Partial Prerendering and how it works → [YouTube (10 minutes)](https://www.youtube.com/watch?v=MTcPrTIBkpA). ### Maximizing the static shell The deeper your async work sits in the tree, the more of the page can be prerendered. This is the structural pattern Cache Components rewards: a general practice worth applying everywhere, and the foundation for the instant navigation and prefetching that follow. It applies to all [runtime APIs](#working-with-runtime-apis) and async operations like data fetches. Consider a layout that destructures `params` at the top level: ```tsx filename="app/shop/[slug]/layout.tsx" export default async function Layout({ children, params, }: LayoutProps<'/shop/[slug]'>) { const { slug } = await params return (

{slug}

{children}
) } ``` If this param is dynamic (not provided by [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params)), it is runtime data and the layout cannot be prerendered. However, it is often possible to read the parameter value further down the tree. Instead of awaiting at the layout level, pass the params promise down and await there: ```tsx filename="app/shop/[slug]/layout.tsx" highlight={3-4,11-16} import { Suspense } from 'react' // Not async: this layout never awaits params export default function Layout({ children, params, }: LayoutProps<'/shop/[slug]'>) { return (
Loading...

}> {/* await happens inside the boundary, so the shell still renders */} {params.then(({ slug }) => ( ))} {children} ) } function SlugHeading({ slug }: { slug: string }) { return

{slug}

} ``` Now ``, `{children}`, and the Suspense fallback are all part of the static shell. Only `SlugHeading` streams in at request time. You can also pass the entire `params` promise and await it in the child component. The same principle applies to `cookies()`, `headers()`, `searchParams`, and data fetches. See [Reusing data with `React.cache`](/docs/app/getting-started/fetching-data#reusing-data-with-reactcache) for a related pattern. For a complete workflow, see [Optimizing the static shell](/docs/app/guides/optimizing-the-static-shell). ### Instant navigation Cache Components shipped in 16.0.0 with verification that direct visits to a route produce a static shell. Client navigations are different: a `` boundary that covers a direct visit may not be part of the render during a transition. Getting that structure right is easier when the framework steps in. Cache Components now validates these navigations too, giving you insights and errors that guide you to make navigations to your route instant. For example, wrap data in ``, cache it with `use cache`, or move where the access happens. Read the [Instant navigation guide](/docs/app/guides/instant-navigation) for examples and inspection tools. ### Prefetching With [Partial Prefetching](/docs/app/api-reference/config/next-config-js/partialPrefetching) enabled, the router prefetches each route's [App Shell](/docs/app/glossary#app-shell) by default. The App Shell includes static content and session data derived from `cookies()` and `headers()`. To also prefetch cached content that depends on a link's **URL data**, such as `searchParams` or dynamic `params`, set `prefetch={true}` on that link. With [``](/docs/app/api-reference/components/link#prefetch) pointing at a [Partial Prefetching](/docs/app/api-reference/config/next-config-js/partialPrefetching) route, Next.js renders that route's component tree again at prefetch time, this time with the destination URL resolved. The same rules apply, but more of the tree resolves now that its `searchParams` and `params` are in scope: - [`use cache`](#usage) called with values extracted from runtime APIs (passed as arguments) joins the per-link prefetch - [`use cache: private`](/docs/app/api-reference/directives/use-cache-private) executes on the server, reads runtime data directly, and caches the result in the browser as part of the per-link prefetch - [``](#streaming-uncached-data) fallbacks stay in the prefetched UI while uncached content streams at request time This per-link prefetch includes cached content that resolves after the destination URL is known. It costs a server invocation per prefetchable link. For example, take a search page that reads `searchParams` from the URL: ```tsx filename="app/search/page.tsx" import { Suspense } from 'react' export default function SearchPage(props: PageProps<'/search'>) { return ( Loading results...

}> ) } async function Results({ searchParams, }: Pick, 'searchParams'>) { const { q } = await searchParams const results = await search(q) return (
    {results.map((result) => (
  • {result.title}
    • ))}
) } async function search(query: string | string[] | undefined) { 'use cache' return db.search(query) } ``` On a direct visit, `` streams in behind the fallback. When a [``](/docs/app/api-reference/components/link) to `/search?q=shoes` is prefetched, the framework resolves `searchParams` from the link's URL, so the cached `search` result is included in the runtime prerender before the click. The browser then reuses it until its [`stale`](/docs/app/api-reference/functions/cacheLife#stale) time passes or the `searchParams` change. See [Adopting Partial Prefetching](/docs/app/guides/adopting-partial-prefetching) to understand how `` prefetching behaves and how to adopt it. See the [Optimizing prefetching guide](/docs/app/guides/optimizing-prefetching) for full patterns and the [`prefetch` reference](/docs/app/api-reference/file-conventions/route-segment-config/prefetch) for all modes. ## Where cached content is stored A cached function's output is serialized into an **RSC payload**, at build time or at runtime. This payload is what everything else works from. Next.js renders it into HTML, keeps it in a server or remote store, or sends it to the browser, and [`cacheLife`](/docs/app/api-reference/functions/cacheLife) sets how long each copy stays fresh: - **Prerendered HTML.** The payload is rendered to HTML and stored on disk when self-hosting, or in your platform's durable storage behind a CDN. That HTML is the [static shell](#prerendering) at build time and the concrete page after an [ISR](#incremental-static-regeneration) upgrade, with [`revalidate`](/docs/app/api-reference/functions/cacheLife#revalidate) and [`expire`](/docs/app/api-reference/functions/cacheLife#expire) controlling when it's rebuilt. - **Shared store.** By default the result stays in a per-instance, in-memory store that is ephemeral on serverless. [`use cache: remote`](/docs/app/api-reference/directives/use-cache-remote) moves it to a durable [cache handler](/docs/app/api-reference/config/next-config-js/cacheHandlers) shared across instances, a network roundtrip that pays off only at a **high hit rate**. - **Browser.** The payload is included in the RSC sent for a client navigation or [prefetch](#prefetching), where the browser keeps it fresh for its [`stale`](/docs/app/api-reference/functions/cacheLife#stale) window. [`use cache: private`](/docs/app/api-reference/directives/use-cache-private) results live only here. > **Good to know:** An [App Shell](/docs/app/glossary#app-shell) that reads `cookies()` or `headers()` is session-specific, cached per session on the client rather than in the shared server cache. All of these stores are scoped to a single deployment. A new deploy starts fresh, new prerenders are built, and `use cache` entries don't carry over, even durable [`remote`](/docs/app/api-reference/directives/use-cache-remote) ones, because the [cache key](/docs/app/api-reference/directives/use-cache#cache-keys) includes the build id. See [Runtime caching considerations](/docs/app/api-reference/directives/use-cache#runtime-caching-considerations) for per-environment behavior and [Self-hosting](/docs/app/guides/self-hosting#caching-and-isr) for configuring the server cache. ## Incremental Static Regeneration In a route with dynamic param segments, [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) prerenders the URLs you list at build time. Any other URL is served the [App Shell](/docs/app/glossary#app-shell) instantly, then upgraded in the background with its now-known params and cached for the next visitor. See [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components) for the full walkthrough. ## Bots and crawlers With [Partial Prerendering](#prerendering), metadata can be dynamic while the rest of the page is prerendered into a static shell. The shell is served immediately and the metadata streams in after. Some bots and crawlers cannot handle this, and need to see the metadata included in the `` tag of the document. Next.js detects them by their user agent, skips the static shell, and renders the page dynamically at request time. Data sources available during the build-time prerender have to be available at request time too. Otherwise the render may throw, and these bots receive a 500 error. See [Bots and crawlers](/docs/app/guides/streaming#bots-and-crawlers) in the Streaming guide for which user agents this covers and how to change the list. --- ### 01 App 01 Getting Started 09 Revalidating (`docs/01-app/01-getting-started/09-revalidating.mdx`) --- title: Revalidating description: Learn how to revalidate cached data using time-based and on-demand strategies. related: title: API Reference description: Learn more about the APIs mentioned on this page. links: - app/api-reference/functions/cacheLife - app/api-reference/functions/cacheTag - app/api-reference/functions/revalidateTag - app/api-reference/functions/updateTag - app/api-reference/functions/revalidatePath --- > This page covers revalidation with [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents), enabled by setting [`cacheComponents: true`](/docs/app/api-reference/config/next-config-js/cacheComponents) in your `next.config.ts` file. If you're not using Cache Components, see the [Caching and Revalidating (Previous Model)](/docs/app/guides/caching-without-cache-components) guide. Revalidation is the process of updating cached data. It lets you keep serving fast, cached responses while ensuring content stays fresh. There are two strategies: - **Time-based revalidation**: Automatically refresh cached data after a set duration using [`cacheLife`](#cachelife). - **On-demand revalidation**: Manually invalidate cached data after a mutation using [`revalidateTag`](#revalidatetag), [`updateTag`](#updatetag), or [`revalidatePath`](#revalidatepath). ## `cacheLife` [`cacheLife`](/docs/app/api-reference/functions/cacheLife) controls how long cached data remains valid. Use it inside a [`use cache`](/docs/app/api-reference/directives/use-cache) scope to set the cache lifetime. ```tsx filename="app/lib/data.ts" highlight={1,4,5} import { cacheLife } from 'next/cache' export async function getProducts() { 'use cache' cacheLife('hours') return db.query('SELECT * FROM products') } ``` `cacheLife` accepts a profile name or a custom configuration object: | Profile | `stale` | `revalidate` | `expire` | | --------- | ------- | ------------ | -------- | | `default` | 5m | 15m | never | | `seconds` | 30s | 1s | 60s | | `minutes` | 5m | 1m | 1h | | `hours` | 5m | 1h | 1d | | `days` | 5m | 1d | 1w | | `weeks` | 5m | 1w | 30d | | `max` | 5m | 30d | 1y | For fine-grained control, pass an object: ```tsx highlight={2-6} 'use cache' cacheLife({ stale: 3600, // 1 hour until considered stale revalidate: 7200, // 2 hours until revalidated expire: 86400, // 1 day until expired }) ``` > **Good to know:** A cache is considered "short-lived" when it uses the `seconds` profile, `revalidate: 0`, or `expire` under 5 minutes. Short-lived caches are automatically excluded from prerenders and become dynamic holes instead. See [Prerendering behavior](/docs/app/api-reference/functions/cacheLife#prerendering-behavior) for details. See the [`cacheLife` API reference](/docs/app/api-reference/functions/cacheLife) for all profiles and custom configuration options. ## `cacheTag` [`cacheTag`](/docs/app/api-reference/functions/cacheTag) lets you tag cached data so it can be invalidated on-demand. Use it inside a [`use cache`](/docs/app/api-reference/directives/use-cache) scope: ```tsx filename="app/lib/data.ts" switcher import { cacheTag } from 'next/cache' export async function getProducts() { 'use cache' cacheTag('products') return db.query('SELECT * FROM products') } ``` ```jsx filename="app/lib/data.js" switcher import { cacheTag } from 'next/cache' export async function getProducts() { 'use cache' cacheTag('products') return db.query('SELECT * FROM products') } ``` Once tagged, invalidate the cache using [`revalidateTag`](#revalidatetag) or [`updateTag`](#updatetag). See the [`cacheTag` API reference](/docs/app/api-reference/functions/cacheTag) to learn more. ## `revalidateTag` `revalidateTag` invalidates cache entries by tag using stale-while-revalidate semantics — stale content is served immediately while fresh content loads in the background. This is ideal for content where a slight delay in updates is acceptable, like blog posts or product catalogs. ```tsx filename="app/lib/actions.ts" highlight={1,5} switcher import { revalidateTag } from 'next/cache' export async function updateUser(id: string) { // Mutate data revalidateTag('user', 'max') // Recommended: stale-while-revalidate } ``` ```jsx filename="app/lib/actions.js" highlight={1,5} switcher import { revalidateTag } from 'next/cache' export async function updateUser(id) { // Mutate data revalidateTag('user', 'max') // Recommended: stale-while-revalidate } ``` You can reuse the same tag in multiple functions to revalidate them all at once. Call `revalidateTag` in a [Server Action](/docs/app/getting-started/mutating-data) or [Route Handler](/docs/app/api-reference/file-conventions/route). > **Good to know:** The second argument sets how long stale content can be served while fresh content generates in the background. Once it expires, subsequent requests block until fresh content is ready. Using `'max'` gives the longest stale window. See the [`revalidateTag` API reference](/docs/app/api-reference/functions/revalidateTag) to learn more. ## `updateTag` `updateTag` immediately expires cached data for read-your-own-writes scenarios — the user sees their change right away instead of stale content. Unlike `revalidateTag`, it can only be used in [Server Actions](/docs/app/guides/server-actions). ```tsx filename="app/lib/actions.ts" highlight={1,12} switcher import { updateTag } from 'next/cache' import { redirect } from 'next/navigation' export async function createPost(formData: FormData) { const post = await db.post.create({ data: { title: formData.get('title'), content: formData.get('content'), }, }) updateTag('posts') redirect(`/posts/${post.id}`) } ``` ```jsx filename="app/lib/actions.js" highlight={1,12} switcher import { updateTag } from 'next/cache' import { redirect } from 'next/navigation' export async function createPost(formData) { const post = await db.post.create({ data: { title: formData.get('title'), content: formData.get('content'), }, }) updateTag('posts') redirect(`/posts/${post.id}`) } ``` | | `updateTag` | `revalidateTag` | | ------------ | --------------------------------------------- | ------------------------------------ | | **Where** | Server Actions only | Server Actions and Route Handlers | | **Behavior** | Immediately expires cache | Stale-while-revalidate | | **Use case** | Read-your-own-writes (user sees their change) | Background refresh (slight delay OK) | See the [`updateTag` API reference](/docs/app/api-reference/functions/updateTag) to learn more. ## `revalidatePath` `revalidatePath` invalidates all cached data for a specific route path. Use it when you want to revalidate a route without knowing which tags are associated with it. ```tsx filename="app/lib/actions.ts" highlight={1,5} switcher import { revalidatePath } from 'next/cache' export async function updateUser(id: string) { // Mutate data revalidatePath('/profile') } ``` ```jsx filename="app/lib/actions.js" highlight={1,5} switcher import { revalidatePath } from 'next/cache' export async function updateUser(id) { // Mutate data revalidatePath('/profile') } ``` > **Good to know**: Prefer tag-based revalidation (`revalidateTag`/`updateTag`) over path-based when possible — it's more precise and avoids over-invalidating. See the [`revalidatePath` API reference](/docs/app/api-reference/functions/revalidatePath) to learn more. ## What should I cache? Cache data that doesn't depend on [runtime data](/docs/app/getting-started/caching#working-with-runtime-apis) and that you're OK serving from cache for a period of time. Use `use cache` with `cacheLife` to describe that behavior. When content doesn't need time-based revalidation, for example data from a CMS, use [`cacheTag`](#cachetag) and a long [`cacheLife`](#cachelife) like `max` to keep it in the static shell. Configure the content source to trigger a webhook, or other notification, that calls [`revalidateTag`](#revalidatetag) when the content changes. This reduces unnecessary time-based revalidation for content that hasn't changed. > **Good to know:** In serverless environments, in-memory cache entries may not persist across revalidations. See [runtime caching considerations](/docs/app/api-reference/directives/use-cache#runtime-caching-considerations) for details. --- ### 01 App 01 Getting Started 10 Error Handling (`docs/01-app/01-getting-started/10-error-handling.mdx`) --- title: Error Handling description: Learn how to display expected errors and handle uncaught exceptions. related: title: API Reference description: Learn more about the features mentioned in this page by reading the API Reference. links: - app/api-reference/functions/redirect - app/api-reference/file-conventions/error - app/api-reference/functions/catchError - app/api-reference/functions/not-found - app/api-reference/file-conventions/not-found --- Errors can be divided into two categories: [expected errors](#handling-expected-errors) and [uncaught exceptions](#handling-uncaught-exceptions). This page will walk you through how you can handle these errors in your Next.js application. ## Handling expected errors Expected errors are those that can occur during the normal operation of the application, such as those from [server-side form validation](/docs/app/guides/forms) or failed requests. These errors should be handled explicitly and returned to the client. ### Server Functions You can use the [`useActionState`](https://react.dev/reference/react/useActionState) hook to handle expected errors in [Server Functions](https://react.dev/reference/rsc/server-functions). For these errors, avoid using `try`/`catch` blocks and throw errors. Instead, model expected errors as return values. ```ts filename="app/actions.ts" switcher 'use server' export async function createPost(prevState: any, formData: FormData) { const title = formData.get('title') const content = formData.get('content') const res = await fetch('https://api.vercel.app/posts', { method: 'POST', body: { title, content }, }) const json = await res.json() if (!res.ok) { return { message: 'Failed to create post' } } } ``` ```js filename="app/actions.js" switcher 'use server' export async function createPost(prevState, formData) { const title = formData.get('title') const content = formData.get('content') const res = await fetch('https://api.vercel.app/posts', { method: 'POST', body: { title, content }, }) const json = await res.json() if (!res.ok) { return { message: 'Failed to create post' } } } ``` You can pass your action to the `useActionState` hook and use the returned `state` to display an error message. ```tsx filename="app/ui/form.tsx" highlight={11,19} switcher 'use client' import { useActionState } from 'react' import { createPost } from '@/app/actions' const initialState = { message: '', } export function Form() { const [state, formAction, pending] = useActionState(createPost, initialState) return (