fetch
Next.js extends the native Web fetch()
API to allow each request on the server to set its own persistent caching semantics.
In the browser, the cache
option indicates how a fetch request will interact with the browser's HTTP cache. With this extension, cache
indicates how a server-side fetch request will interact with the framework's persistent HTTP cache.
You can call fetch
with async
and await
directly within Server Components.
export default async function Page() {
// This request should be cached until manually invalidated.
// Similar to `getStaticProps`.
// `force-cache` is the default and can be omitted.
const staticData = await fetch(`https://...`, { cache: 'force-cache' })
// This request should be refetched on every request.
// Similar to `getServerSideProps`.
const dynamicData = await fetch(`https://...`, { cache: 'no-store' })
// This request should be cached with a lifetime of 10 seconds.
// Similar to `getStaticProps` with the `revalidate` option.
const revalidatedData = await fetch(`https://...`, {
next: { revalidate: 10 },
})
return <div>...</div>
}
fetch(url, options)
Since Next.js extends the Web fetch()
API, you can use any of the native options available.
options.cache
Configure how the request should interact with Next.js Data Cache.
fetch(`https://...`, { cache: 'force-cache' | 'no-store' })
force-cache
(default) - Next.js looks for a matching request in its Data Cache.- If there is a match and it is fresh, it will be returned from the cache.
- If there is no match or a stale match, Next.js will fetch the resource from the remote server and update the cache with the downloaded resource.
no-store
- Next.js fetches the resource from the remote server on every request without looking in the cache, and it will not update the cache with the downloaded resource.
Good to know:
- If you don't provide a
cache
option, Next.js will default toforce-cache
, unless a dynamic function such ascookies()
is used, in which case it will default tono-store
.- The
no-cache
option behaves the same way asno-store
in Next.js.
options.next.revalidate
fetch(`https://...`, { next: { revalidate: false | 0 | number } })
Set the cache lifetime of a resource (in seconds).
false
- Cache the resource indefinitely. Semantically equivalent torevalidate: Infinity
. The HTTP cache may evict older resources over time.0
- Prevent the resource from being cached.number
- (in seconds) Specify the resource should have a cache lifetime of at mostn
seconds.
Good to know:
- If an individual
fetch()
request sets arevalidate
number lower than the defaultrevalidate
of a route, the whole route revalidation interval will be decreased.- If two fetch requests with the same URL in the same route have different
revalidate
values, the lower value will be used.- As a convenience, it is not necessary to set the
cache
option ifrevalidate
is set to a number since0
impliescache: 'no-store'
and a positive value impliescache: 'force-cache'
.- Conflicting options such as
{ revalidate: 0, cache: 'force-cache' }
or{ revalidate: 10, cache: 'no-store' }
will cause an error.
options.next.tags
fetch(`https://...`, { next: { tags: ['collection'] } })
Set the cache tags of a resource. Data can then be revalidated on-demand using revalidateTag
. The max length for a custom tag is 256 characters and the max tag items is 64.
Version History
Version | Changes |
---|---|
v13.0.0 | fetch introduced. |
Was this helpful?