cacheTag example with basic tagging
Example of basic cacheTag usage: ```tsx import { cacheTag } from 'next/cache' export async function getData() { 'use cache' cacheTag('my-data') const data = await fetch('/api/data') return data } ```
Next.js · API reference · all subjects
functions
556 notes in this subject, read out of this brain and free to use. This is page 1 of 10.
cacheTag limits and constraints
A single cacheTag() call accepts up to 128 tags, each with a maximum length of 256 characters. Tags longer than 256 characters are skipped, and any tags past the 128th in one call are dropped. Both cases log a console warning.
cacheTag example with multiple tags
Example of applying multiple tags to a single cache entry: ```tsx cacheTag('tag-one', 'tag-two') ```
cacheTag function import and location
The cacheTag function is imported from 'next/cache'.
updateTag vs revalidateTag usage scenarios
updateTag is used for read-your-own-writes scenarios (forms and user-triggered mutations) where a user makes a change and the next read should fetch fresh data immediately. updateTag is only available inside Server Functions. revalidateTag is used when it is acceptable to serve stale data while revalidation happens in the background, or when revalidating from a Route Handler or other context.
cacheComponents config flag requirement
To use cacheTag, the cacheComponents flag must be enabled in next.config.js. Set cacheComponents: true in the NextConfig object.
cacheTag function parameters
The cacheTag function takes one or more string values as parameters. Multiple tags can be assigned to a single cache entry by passing multiple string values.
cacheTag example with component tagging
Example of tagging cached data within a Server Component: ```tsx import { cacheTag } from 'next/cache' interface BookingsProps { type: string } export async function Bookings({ type = 'haircut' }: BookingsProps) { 'use cache' cacheTag('bookings-data') async function getBookingsData() { const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`) return data } return //... } ```
revalidateTag Server Function example
Example of using revalidateTag to invalidate the cache for a specific tag: ```tsx 'use server' import { revalidateTag } from 'next/cache' export async function updateBookings() { await updateBookingData() revalidateTag('bookings-data', 'max') } ```
updateTag Server Function example
Example of using updateTag in a Server Function to purge cache after mutation: ```tsx 'use server' import { updateTag } from 'next/cache' export default async function submit() { await addPost() updateTag('my-data') } ```
cacheTag example with dynamic tag values
Example of using data returned from an async function to create cache tags: ```tsx import { cacheTag } from 'next/cache' interface BookingsProps { type: string } export async function Bookings({ type = 'haircut' }: BookingsProps) { async function getBookingsData() { 'use cache' const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`) cacheTag('bookings-data', data.id) return data } return //... } ```
cacheTag usage within 'use cache' directive
cacheTag is called within a function or component marked with 'use cache' directive. The function must be inside a cached function or component for tagging to work.
cacheTag purpose and functionality
The cacheTag function allows you to tag cached data for on-demand invalidation. By associating tags with cache entries, you can selectively purge or revalidate specific cache entries without affecting other cached data.
cacheTag idempotent behavior
Applying the same tag multiple times has no additional effect. Tags are idempotent.
after in Server Component with request data example
Example showing after in a Server Component where request data is read before the callback: ```tsx import { after } from 'next/server' import { cookies, headers } from 'next/headers' import { logUserAction } from '@/app/utils' export default async function Page() { // Read request data before `after` — this is allowed const userAgent = (await headers()).get('user-agent') || 'unknown' const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous' after(() => { // Use the values read above logUserAction({ sessionCookie, userAgent }) }) return <h1>My Page</h1> } ```
after function usage contexts
The after function can be used in Server Components (including generateMetadata), Server Functions, Route Handlers, and Proxy.
after cannot use cookies or headers in Server Components
Server Components (including pages, layouts, and generateMetadata) cannot use cookies, headers, or other Request-time APIs inside after. This is because Next.js needs to know which part of the component tree accesses request data to support Partial Prerendering and Cache Components, but after runs after React's rendering lifecycle. Calling cookies() or headers() inside the after callback in a Server Component will throw a runtime error.
after in Route Handler example
Example showing after used in a Route Handler with cookies and headers for logging user activity: ```ts import { after } from 'next/server' import { cookies, headers } from 'next/headers' import { logUserAction } from '@/app/utils' export async function POST(request: Request) { // Perform mutation // ... // Log user activity for analytics after(async () => { const userAgent = (await headers()).get('user-agent') || 'unknown' const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous' logUserAction({ sessionCookie, userAgent }) }) return new Response(JSON.stringify({ status: 'success' }), { status: 200, headers: { 'Content-Type': 'application/json' }, }) } ```
after function overview
The after function allows you to schedule work to be executed after a response (or prerender) is finished. This is useful for tasks and side effects that should not block the response, such as logging and analytics. It accepts a callback function that will be executed after the response (or prerender) is finished.
after with cookies and headers in Route Handlers and Server Functions
You can call cookies and headers directly inside the after callback when used in Route Handlers and Server Functions. This is useful for logging activity after a mutation or API request.
after can be nested
The after function can be nested inside other after calls. You can create utility functions that wrap after calls to add additional functionality.
after with Cache Components pattern
When using Cache Components, components that access request data like cookies or headers must be wrapped in Suspense so the rest of the page can be prerendered into a static shell. You can combine this pattern with after by reading request data in a dynamic component and passing it into after.
after with React cache deduplication
You can use React cache to deduplicate functions called inside after.
after is not a Request-time API
Calling after does not cause a route to become dynamic. It is not a Request-time API. If it is used within a static page, the callback will execute at build time, or whenever a page is revalidated.
after executes even on errors
The after callback will be executed even if the response did not complete successfully, including when an error is thrown or when notFound or redirect is called.
after version history
The after function became stable in v15.1.0. It was introduced as unstable_after in v15.0.0-rc.
after duration and timeout
The after function will run for the platform's default or configured max duration of your route. If your platform supports it, you can configure the timeout limit using the maxDuration route segment config.
after platform support
The after function is supported on Node.js server and Docker container deployments. It is not supported in static export. For adapters, support is platform-specific.
after in Layout example
Example showing after used in a layout: ```tsx import { after } from 'next/server' import { log } from '@/app/utils' export default function Layout({ children }: { children: React.ReactNode }) { after(() => { // Execute after the layout is rendered and sent to the user log() }) return <>{children}</> } ```
after serverless implementation with waitUntil
Using after in a serverless context requires waiting for asynchronous tasks to finish after the response has been sent. This is achieved using a primitive called waitUntil(promise), which extends the lifetime of a serverless invocation until all promises have settled. Next.js accesses waitUntil via globalThis[Symbol.for('@next/request-context')], which is expected to contain an object with a get() method that returns a NextRequestContextValue object with an optional waitUntil property.
after with Cache Components and Suspense example
Example showing after combined with Cache Components and Suspense: ```tsx import { Suspense } from 'react' import { after } from 'next/server' import { cookies } from 'next/headers' import { logUserAction } from '@/app/utils' export default function Page() { return ( <> <h1>Part of the static shell</h1> <Suspense fallback={<p>Loading...</p>}> <DynamicContent /> </Suspense> </> ) } async function DynamicContent() { const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous' // Schedule work after the response is sent after(() => { logUserAction({ sessionCookie }) }) return <p>Your session: {sessionCookie}</p> } ```
after with request data in Server Components workaround
If you need request data inside an after callback in a Server Component, read it beforehand during the component's rendering lifecycle and pass the values into the after callback via closure.
connection() basic usage example
Example: import { connection } from 'next/server'; export default async function Page() { await connection(); // prerendering stops here - following code only runs at request time; const rand = Math.random(); return <span>{rand}</span>; } This shows how connection() prevents prerendering of code that relies on request-time values.
connection() import location
The connection() function is imported from 'next/server'.
connection() vs io() with Cache Components
With Cache Components, io() is preferred for excluding content from the static shell because it works the same way as connection() but can also be cached and prefetched. Reach for connection() only when rendering should wait for a real user request.
connection() with synchronous database drivers
For synchronous database drivers like better-sqlite3, queries would normally complete during prerendering. You should call connection() before your query to exclude it from prerendering. Any component that calls a function containing connection() will be excluded from prerendering, along with the rest of its output.
connection() function purpose and behavior
The connection() function allows you to indicate that rendering should wait for an incoming user request before continuing. It is useful when a component does not use Request-time APIs like cookies or headers, but still needs to produce different output per request, such as Math.random() or new Date(). After awaiting connection(), the following code only runs at request time and is excluded from prerendering.
connection() use case example with synchronous database
Example: import { connection } from 'next/server'; import Database from 'better-sqlite3'; const db = new Database('app.db'); export async function getVisitorCount() { await connection(); return db.prepare('SELECT value FROM counters WHERE name = ?').get('visitors'); } This ensures the database query only runs at request time, not during prerendering.
connection() replaces unstable_noStore
The connection() function replaces unstable_noStore to better align with the future of Next.js.
connection() version history
The connection() function was introduced in v15.0.0-RC and stabilized in v15.0.0.
connection() function signature and return type
The connection() function has the signature: function connection(): Promise<void>. It does not accept any parameters and returns a void Promise that is not meant to be consumed.
catchError fallback parameter specification
catchError accepts a single argument: a fallback function that renders error UI when an error is caught. The fallback function receives two arguments: props (the props passed to the wrapper component, excluding children) and errorInfo (an object containing error information). The fallback function must be a Client Component or defined in a 'use client' module.
Use retry() instead of reset() for Server Component errors
In most cases, use retry() instead of reset() when recovering from errors with catchError. The reset() function only clears the error state and re-renders without re-fetching, which means it won't recover from Server Component errors. The retry() function re-fetches and re-renders the error boundary's children.
catchError usage wrapping component children
Example of using catchError in a component: ```tsx import ErrorWrapper from '../custom-error-boundary' export default function Component({ children }: { children: React.ReactNode }) { return <ErrorWrapper title="Dashboard Error">{children}</ErrorWrapper> } ``` This shows how to wrap component children with the error boundary returned by catchError.
catchError component-level scope vs error.js file convention
Unlike the error.js file convention which is scoped to route segments, catchError can be used to wrap any part of your component tree for component-level error recovery. Props passed to the wrapper component are forwarded to the fallback function, making it easy to create reusable error UIs with different configurations.
catchError basic usage example
Example of defining a catchError error boundary: ```tsx 'use client' import { catchError, type ErrorInfo } from 'next/error' function ErrorFallback(props: { title: string }, { error, retry }: ErrorInfo) { return ( <div> <h2>{props.title}</h2> <p>{error.message}</p> <button onClick={() => retry()}>Try again</button> </div> ) } export default catchError(ErrorFallback) ``` This shows how to create an error boundary fallback function that receives a title prop and error information, displaying an error message with a retry button.
catchError version history
catchError became stable in v16.3.0. It was introduced as unstable_catchError in v16.2.0.
catchError with both retry and reset example
Example of error recovery with both retry and reset functions: ```tsx 'use client' import { catchError, type ErrorInfo } from 'next/error' function ErrorFallback(props: {}, { error, retry, reset }: ErrorInfo) { return ( <div> <p>{error.message}</p> <button onClick={() => retry()}>Try again</button> <button onClick={() => reset()}>Reset</button> </div> ) } export default catchError(ErrorFallback) ``` This shows how to provide both retry and reset buttons for error recovery options.
catchError returns component accepting props and children
catchError returns a React component that accepts the same props as the fallback's first argument plus children, wraps children in an error boundary, and renders the fallback when an error is caught in children.
error.js does not need catchError wrapper
You do not need to wrap error.js default exports with catchError. The error.js file convention already renders inside a built-in error boundary provided by Next.js.
catchError built-in error recovery with retry
catchError provides built-in error recovery through the retry() function which re-renders the page inside a Transition, preserving Client Components state outside of the error boundary.
catchError clears error state on client navigation
The error state automatically clears when doing a client navigation to a different route when using catchError.
catchError function creates error boundary
The catchError function creates a component that wraps its children in an error boundary. It provides a programmatic alternative to the error.js file convention, enabling component-level error recovery anywhere in your component tree. catchError can be called from Client Components.
catchError handles redirect and notFound
catchError is framework-aware and handles APIs like redirect() and notFound() seamlessly, since these work by throwing special errors under the hood. catchError will not accidentally catch these framework errors.
catchError errorInfo object properties
The errorInfo object passed to the fallback function contains three properties: error (Error type, the error instance that was caught), retry (() => void, re-fetches and re-renders the error boundary's children, and if successful replaces the fallback with the re-rendered result), and reset (() => void, resets the error state and re-renders without re-fetching).
catchError with server-rendered fallback example
Example of using server-rendered content as an error fallback: ```tsx // app/error-boundary.tsx 'use client' import { catchError, type ErrorInfo } from 'next/error' function ErrorFallback( props: { fallback: React.ReactNode }, errorInfo: ErrorInfo ) { return props.fallback } export default catchError(ErrorFallback) ``` ```tsx // app/some-component.tsx import ErrorBoundary from '../error-boundary' async function ErrorFallback() { const data = await getData() return <div>{data.message}</div> } export default function Component({ children }: { children: React.ReactNode }) { return <ErrorBoundary fallback={<ErrorFallback />}>{children}</ErrorBoundary> } ``` This shows how to pass server-rendered content as a prop to display data-driven fallback UI. Note that this pattern eagerly renders the fallback on every page render, even when no error occurs.
cookies function usage locations
The cookies function allows you to read HTTP incoming request cookies in Server Components, and read/write outgoing request cookies in Server Functions or Route Handlers.
cookies function is async and requires await
The cookies function is an async function that returns a promise. You must use async/await or React's use function to access cookies. In version 14 and earlier, cookies was a synchronous function, but in Next.js 15 it became asynchronous.
cookies methods reference
The cookies function provides the following methods: get(name) returns an Object with the name and value; getAll() returns an Array of objects with all cookies; has(name) returns a Boolean; set(name, value, options) sets the outgoing request cookie with no return; delete(name) deletes the cookie with no return; toString() returns a String representation of the cookies.
cookies set options reference
When calling set(name, value, options), the options object supports: name (String) - specifies the name of the cookie; value (String) - specifies the value to be stored; expires (Date) - defines the exact date when the cookie will expire; maxAge (Number) - sets the cookie's lifespan in seconds; domain (String) - specifies the domain where the cookie is available; path (String, default: '/') - limits the cookie's scope to a specific path; secure (Boolean) - ensures the cookie is sent only over HTTPS; httpOnly (Boolean) - restricts the cookie to HTTP requests, preventing client-side access; sameSite (Boolean, 'lax', 'strict', 'none') - controls cross-site request behavior; priority (String: 'low', 'medium', 'high') - specifies the cookie's priority; partitioned (Boolean) - indicates whether the cookie is partitioned. Only path has a default value.