unstable_expirePath

unstable_expirePath allows you to purge cached data on-demand for a specific path.

Good to know:

• unstable_expirePath is available in both Node.js and Edge runtimes.
• unstable_expirePath only invalidates the cache when the included path is next visited. This means calling unstable_expirePath with a dynamic route segment will not immediately trigger many expirations at once. The invalidation only happens when the path is next visited.
• Currently, unstable_expirePath invalidates all the routes in the client-side Router Cache when used in a server action. This behavior is temporary and will be updated in the future to apply only to the specific path.
• Using unstable_expirePath invalidates only the specific path in the server-side Route Cache.

Reference

Parameters

unstable_expirePath(path: string, type?: 'page' | 'layout'): void;

• path: Either a string representing the filesystem path associated with the data you want to expire (for example, /product/[slug]/page), or the literal route segment (for example, /product/123). Must be less than 1024 characters. This value is case-sensitive.
• type: (optional) 'page' or 'layout' string to change the type of path to expire. If path contains a dynamic segment (for example, /product/[slug]/page), this parameter is required. If path refers to the literal route segment, e.g., /product/1 for a dynamic page (e.g., /product/[slug]/page), you should not provide type.

Returns

unstable_expirePath does not return a value.

Examples

Expiring a specific URL

import { unstable_expirePath } from 'next/cache'
unstable_expirePath('/blog/post-1')

This will purge the cache for one specific URL on the next page visit.

Expiring a page path

import { unstable_expirePath } from 'next/cache'
unstable_expirePath('/blog/[slug]', 'page')
// or with route groups
unstable_expirePath('/(main)/blog/[slug]', 'page')

This will purge the cache any URL that matches the provided page file on the next page visit. This will not invalidate pages beneath the specific page. For example, /blog/[slug] won't invalidate /blog/[slug]/[author].

Expiring a layout path

import { unstable_expirePath } from 'next/cache'
unstable_expirePath('/blog/[slug]', 'layout')
// or with route groups
unstable_expirePath('/(main)/post/[slug]', 'layout')

This will purge the cache on any URL that matches the provided layout file on the next page visit. This will cause pages beneath with the same layout to revalidate on the next visit. For example, in the above case, /blog/[slug]/[another] would also revalidate on the next visit.

Expiring all data

import { unstable_expirePath } from 'next/cache'
 
unstable_expirePath('/', 'layout')

This will purge the Data Cache on the next page visit.

Server Action

You can call unstable_expirePath in a Server Action:

'use server'
 
import { unstable_expirePath } from 'next/cache'
 
export default async function submit() {
  await submitForm()
  unstable_expirePath('/')
}

Route Handler

You can call unstable_expirePath in a Route Handler:

import { unstable_expirePath } from 'next/cache'
import type { NextRequest } from 'next/server'
 
export async function GET(request: NextRequest) {
  const path = request.nextUrl.searchParams.get('path')
 
  if (path) {
    unstable_expirePath(path)
    return Response.json({ revalidated: true, now: Date.now() })
  }
 
  return Response.json({
    expired: false,
    now: Date.now(),
    message: 'Missing path to expire',
  })
}