Unverified Commit 81bccc93 authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Guide users to `experimental.cacheComponents` config (#84121)

In error messages and in docs for `'use cache'` and related APIs, we now
guide users to the `experimental.cacheComponents` config instead of
`experimental.useCache`.

closes NAR-410
parent ce4d40b0
...@@ -3191,7 +3191,7 @@ fn emit_error(error_kind: ServerActionsErrorKind) { ...@@ -3191,7 +3191,7 @@ fn emit_error(error_kind: ServerActionsErrorKind) {
span, span,
formatdoc! { formatdoc! {
r#" r#"
Unknown cache kind "{cache_kind}". Please configure a cache handler for this kind in the "experimental.cacheHandlers" object in your Next.js config. Unknown cache kind "{cache_kind}". Please configure a cache handler for this kind in the `experimental.cacheHandlers` object in your Next.js config.
"# "#
}, },
), ),
...@@ -3199,7 +3199,7 @@ fn emit_error(error_kind: ServerActionsErrorKind) { ...@@ -3199,7 +3199,7 @@ fn emit_error(error_kind: ServerActionsErrorKind) {
span, span,
formatdoc! { formatdoc! {
r#" r#"
To use "{directive}", please enable the experimental feature flag "useCache" in your Next.js config. To use "{directive}", please enable the feature flag `experimental.cacheComponents` in your Next.js config.
Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
"# "#
......
x Unknown cache kind "x". Please configure a cache handler for this kind in the "experimental.cacheHandlers" object in your Next.js config. x Unknown cache kind "x". Please configure a cache handler for this kind in the `experimental.cacheHandlers` object in your Next.js config.
| |
,-[input.js:1:1] ,-[input.js:1:1]
1 | 'use cache: x' 1 | 'use cache: x'
......
x Unknown cache kind "x". Please configure a cache handler for this kind in the "experimental.cacheHandlers" object in your Next.js config. x Unknown cache kind "x". Please configure a cache handler for this kind in the `experimental.cacheHandlers` object in your Next.js config.
| |
,-[input.js:2:1] ,-[input.js:2:1]
1 | export async function foo() { 1 | export async function foo() {
......
x To use "use cache", please enable the experimental feature flag "useCache" in your Next.js config. x To use "use cache", please enable the feature flag `experimental.cacheComponents` in your Next.js config.
| |
| Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage | Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
| |
......
x To use "use cache: x", please enable the experimental feature flag "useCache" in your Next.js config. x To use "use cache: x", please enable the feature flag `experimental.cacheComponents` in your Next.js config.
| |
| Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage | Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
| |
......
...@@ -6,7 +6,6 @@ related: ...@@ -6,7 +6,6 @@ related:
title: Related title: Related
description: View related API references. description: View related API references.
links: links:
- app/api-reference/config/next-config-js/useCache
- app/api-reference/config/next-config-js/cacheComponents - app/api-reference/config/next-config-js/cacheComponents
- app/api-reference/config/next-config-js/cacheLife - app/api-reference/config/next-config-js/cacheLife
- app/api-reference/functions/cacheTag - app/api-reference/functions/cacheTag
...@@ -18,14 +17,14 @@ The `use cache` directive allows you to mark a route, React component, or a func ...@@ -18,14 +17,14 @@ The `use cache` directive allows you to mark a route, React component, or a func
## Usage ## Usage
`use cache` is currently an experimental feature. To enable it, add the [`useCache`](/docs/app/api-reference/config/next-config-js/useCache) option to your `next.config.ts` file: `use cache` is currently an experimental feature. To enable it, add the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) option to your `next.config.ts` file:
```ts filename="next.config.ts" switcher ```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next' import type { NextConfig } from 'next'
const nextConfig: NextConfig = { const nextConfig: NextConfig = {
experimental: { experimental: {
useCache: true, cacheComponents: true,
}, },
} }
...@@ -36,15 +35,13 @@ export default nextConfig ...@@ -36,15 +35,13 @@ export default nextConfig
/** @type {import('next').NextConfig} */ /** @type {import('next').NextConfig} */
const nextConfig = { const nextConfig = {
experimental: { experimental: {
useCache: true, cacheComponents: true,
}, },
} }
module.exports = nextConfig module.exports = nextConfig
``` ```
> **Good to know:** `use cache` can also be enabled with the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) option.
Then, add `use cache` at the file, component, or function level: Then, add `use cache` at the file, component, or function level:
```tsx ```tsx
......
...@@ -809,5 +809,14 @@ ...@@ -809,5 +809,14 @@
"808": "Invalid binary HMR message: insufficient data (expected %s bytes, got %s)", "808": "Invalid binary HMR message: insufficient data (expected %s bytes, got %s)",
"809": "Invalid binary HMR message of type %s", "809": "Invalid binary HMR message of type %s",
"810": "React debug channel stream error", "810": "React debug channel stream error",
"811": "unsupported transformMode in loader options: %s" "811": "unsupported transformMode in loader options: %s",
"812": "`cacheLife()` is only available with the `experimental.cacheComponents` config.",
"813": "`cacheTag()` is only available with the `experimental.cacheComponents` config.",
"814": "Invalid `cacheLife()` option. Either pass a profile name or object.",
"815": "Unknown \\`cacheLife()\\` profile \"%s\" is not configured in next.config.js\\nmodule.exports = {\n experimental: {\n cacheLife: {\n \"%s\": ...\\n }\n }\n}",
"816": "Unknown \\`cacheLife()\\` profile \"%s\" is not configured in next.config.js\\nDid you mean \"%s\" without the spaces?",
"817": "`cacheLifeProfiles` should always be provided.",
"818": "`cacheLife()` can only be called inside a \"use cache\" function.",
"819": "`cacheTag()` can only be called inside a \"use cache\" function.",
"820": "`cacheLife()` can only be called during App Router rendering at the moment."
} }
import { InvariantError } from '../../shared/lib/invariant-error'
import { workAsyncStorage } from '../app-render/work-async-storage.external' import { workAsyncStorage } from '../app-render/work-async-storage.external'
import { workUnitAsyncStorage } from '../app-render/work-unit-async-storage.external' import { workUnitAsyncStorage } from '../app-render/work-unit-async-storage.external'
...@@ -87,7 +88,7 @@ function validateCacheLife(profile: CacheLife) { ...@@ -87,7 +88,7 @@ function validateCacheLife(profile: CacheLife) {
export function cacheLife(profile: CacheLifeProfiles | CacheLife): void { export function cacheLife(profile: CacheLifeProfiles | CacheLife): void {
if (!process.env.__NEXT_USE_CACHE) { if (!process.env.__NEXT_USE_CACHE) {
throw new Error( throw new Error(
'cacheLife() is only available with the experimental.useCache config.' '`cacheLife()` is only available with the `experimental.cacheComponents` config.'
) )
} }
...@@ -103,7 +104,7 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void { ...@@ -103,7 +104,7 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void {
case 'unstable-cache': case 'unstable-cache':
case undefined: case undefined:
throw new Error( throw new Error(
'cacheLife() can only be called inside a "use cache" function.' '`cacheLife()` can only be called inside a "use cache" function.'
) )
case 'cache': case 'cache':
case 'private-cache': case 'private-cache':
...@@ -116,13 +117,11 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void { ...@@ -116,13 +117,11 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void {
const workStore = workAsyncStorage.getStore() const workStore = workAsyncStorage.getStore()
if (!workStore) { if (!workStore) {
throw new Error( throw new Error(
'cacheLife() can only be called during App Router rendering at the moment.' '`cacheLife()` can only be called during App Router rendering at the moment.'
) )
} }
if (!workStore.cacheLifeProfiles) { if (!workStore.cacheLifeProfiles) {
throw new Error( throw new InvariantError('`cacheLifeProfiles` should always be provided.')
'cacheLifeProfiles should always be provided. This is a bug in Next.js.'
)
} }
// TODO: This should be globally available and not require an AsyncLocalStorage. // TODO: This should be globally available and not require an AsyncLocalStorage.
...@@ -130,12 +129,12 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void { ...@@ -130,12 +129,12 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void {
if (configuredProfile === undefined) { if (configuredProfile === undefined) {
if (workStore.cacheLifeProfiles[profile.trim()]) { if (workStore.cacheLifeProfiles[profile.trim()]) {
throw new Error( throw new Error(
`Unknown cacheLife profile "${profile}" is not configured in next.config.js\n` + `Unknown \`cacheLife()\` profile "${profile}" is not configured in next.config.js\n` +
`Did you mean "${profile.trim()}" without the spaces?` `Did you mean "${profile.trim()}" without the spaces?`
) )
} }
throw new Error( throw new Error(
`Unknown cacheLife profile "${profile}" is not configured in next.config.js\n` + `Unknown \`cacheLife()\` profile "${profile}" is not configured in next.config.js\n` +
'module.exports = {\n' + 'module.exports = {\n' +
' experimental: {\n' + ' experimental: {\n' +
' cacheLife: {\n' + ' cacheLife: {\n' +
...@@ -152,7 +151,7 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void { ...@@ -152,7 +151,7 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void {
Array.isArray(profile) Array.isArray(profile)
) { ) {
throw new Error( throw new Error(
'Invalid cacheLife() option. Either pass a profile name or object.' 'Invalid `cacheLife()` option. Either pass a profile name or object.'
) )
} else { } else {
validateCacheLife(profile) validateCacheLife(profile)
......
...@@ -4,7 +4,7 @@ import { validateTags } from '../lib/patch-fetch' ...@@ -4,7 +4,7 @@ import { validateTags } from '../lib/patch-fetch'
export function cacheTag(...tags: string[]): void { export function cacheTag(...tags: string[]): void {
if (!process.env.__NEXT_USE_CACHE) { if (!process.env.__NEXT_USE_CACHE) {
throw new Error( throw new Error(
'cacheTag() is only available with the experimental.useCache config.' '`cacheTag()` is only available with the `experimental.cacheComponents` config.'
) )
} }
...@@ -20,7 +20,7 @@ export function cacheTag(...tags: string[]): void { ...@@ -20,7 +20,7 @@ export function cacheTag(...tags: string[]): void {
case 'unstable-cache': case 'unstable-cache':
case undefined: case undefined:
throw new Error( throw new Error(
'cacheTag() can only be called inside a "use cache" function.' '`cacheTag()` can only be called inside a "use cache" function.'
) )
case 'cache': case 'cache':
case 'private-cache': case 'private-cache':
...@@ -29,7 +29,7 @@ export function cacheTag(...tags: string[]): void { ...@@ -29,7 +29,7 @@ export function cacheTag(...tags: string[]): void {
workUnitStore satisfies never workUnitStore satisfies never
} }
const validTags = validateTags(tags, 'cacheTag()') const validTags = validateTags(tags, '`cacheTag()`')
if (!workUnitStore.tags) { if (!workUnitStore.tags) {
workUnitStore.tags = validTags workUnitStore.tags = validTags
......
...@@ -41,7 +41,7 @@ describe('use-cache-unknown-cache-kind', () => { ...@@ -41,7 +41,7 @@ describe('use-cache-unknown-cache-kind', () => {
3 | export default async function Page() { 3 | export default async function Page() {
4 | return <p>hello world</p> 4 | return <p>hello world</p>
Unknown cache kind "custom". Please configure a cache handler for this kind in the "experimental.cacheHandlers" object in your Next.js config. Unknown cache kind "custom". Please configure a cache handler for this kind in the \`experimental.cacheHandlers\` object in your Next.js config.
...@@ -53,7 +53,7 @@ describe('use-cache-unknown-cache-kind', () => { ...@@ -53,7 +53,7 @@ describe('use-cache-unknown-cache-kind', () => {
" "
./app/page.tsx ./app/page.tsx
× Module build failed: × Module build failed:
╰─▶ × Error: x Unknown cache kind "custom". Please configure a cache handler for this kind in the "experimental.cacheHandlers" object in your Next.js config. ╰─▶ × Error: x Unknown cache kind "custom". Please configure a cache handler for this kind in the \`experimental.cacheHandlers\` object in your Next.js config.
│ │
│ ,-[1:1] │ ,-[1:1]
│ 1 | 'use cache: custom' │ 1 | 'use cache: custom'
...@@ -75,7 +75,7 @@ describe('use-cache-unknown-cache-kind', () => { ...@@ -75,7 +75,7 @@ describe('use-cache-unknown-cache-kind', () => {
expect(buildOutput).toMatchInlineSnapshot(` expect(buildOutput).toMatchInlineSnapshot(`
" "
./app/page.tsx ./app/page.tsx
Error: x Unknown cache kind "custom". Please configure a cache handler for this kind in the "experimental.cacheHandlers" object in your Next.js config. Error: x Unknown cache kind "custom". Please configure a cache handler for this kind in the \`experimental.cacheHandlers\` object in your Next.js config.
,-[1:1] ,-[1:1]
1 | 'use cache: custom' 1 | 'use cache: custom'
...@@ -124,7 +124,7 @@ describe('use-cache-unknown-cache-kind', () => { ...@@ -124,7 +124,7 @@ describe('use-cache-unknown-cache-kind', () => {
) )
} else { } else {
expect(errorDescription).toMatchInlineSnapshot( expect(errorDescription).toMatchInlineSnapshot(
`" x Unknown cache kind "custom". Please configure a cache handler for this kind in the "experimental.cacheHandlers" object in your Next.js config."` `" x Unknown cache kind "custom". Please configure a cache handler for this kind in the \`experimental.cacheHandlers\` object in your Next.js config."`
) )
} }
...@@ -138,13 +138,13 @@ describe('use-cache-unknown-cache-kind', () => { ...@@ -138,13 +138,13 @@ describe('use-cache-unknown-cache-kind', () => {
3 | export default async function Page() { 3 | export default async function Page() {
4 | return <p>hello world</p> 4 | return <p>hello world</p>
Unknown cache kind "custom". Please configure a cache handler for this kind in the "experimental.cacheHandlers" object in your Next.js config." Unknown cache kind "custom". Please configure a cache handler for this kind in the \`experimental.cacheHandlers\` object in your Next.js config."
`) `)
} else if (isRspack) { } else if (isRspack) {
expect(errorSource).toMatchInlineSnapshot(` expect(errorSource).toMatchInlineSnapshot(`
"./app/page.tsx "./app/page.tsx
× Module build failed: × Module build failed:
╰─▶ × Error: x Unknown cache kind "custom". Please configure a cache handler for this kind in the "experimental.cacheHandlers" object in your Next.js config. ╰─▶ × Error: x Unknown cache kind "custom". Please configure a cache handler for this kind in the \`experimental.cacheHandlers\` object in your Next.js config.
│ | │ |
│ ,-[1:1] │ ,-[1:1]
│ 1 | 'use cache: custom' │ 1 | 'use cache: custom'
...@@ -158,7 +158,7 @@ describe('use-cache-unknown-cache-kind', () => { ...@@ -158,7 +158,7 @@ describe('use-cache-unknown-cache-kind', () => {
} else { } else {
expect(errorSource).toMatchInlineSnapshot(` expect(errorSource).toMatchInlineSnapshot(`
"./app/page.tsx "./app/page.tsx
Error: x Unknown cache kind "custom". Please configure a cache handler for this kind in the "experimental.cacheHandlers" object in your Next.js config. Error: x Unknown cache kind "custom". Please configure a cache handler for this kind in the \`experimental.cacheHandlers\` object in your Next.js config.
,-[1:1] ,-[1:1]
1 | 'use cache: custom' 1 | 'use cache: custom'
......
...@@ -42,7 +42,7 @@ describe('use-cache-without-experimental-flag', () => { ...@@ -42,7 +42,7 @@ describe('use-cache-without-experimental-flag', () => {
3 | export default async function Page() { 3 | export default async function Page() {
4 | return <p>hello world</p> 4 | return <p>hello world</p>
To use "use cache", please enable the experimental feature flag "useCache" in your Next.js config. To use "use cache", please enable the feature flag \`experimental.cacheComponents\` in your Next.js config.
Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
...@@ -56,7 +56,7 @@ describe('use-cache-without-experimental-flag', () => { ...@@ -56,7 +56,7 @@ describe('use-cache-without-experimental-flag', () => {
" "
./app/page.tsx ./app/page.tsx
× Module build failed: × Module build failed:
╰─▶ × Error: x To use "use cache", please enable the experimental feature flag "useCache" in your Next.js config. ╰─▶ × Error: x To use "use cache", please enable the feature flag \`experimental.cacheComponents\` in your Next.js config.
│ | │ |
│ | Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage │ | Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
│ │
...@@ -80,7 +80,7 @@ describe('use-cache-without-experimental-flag', () => { ...@@ -80,7 +80,7 @@ describe('use-cache-without-experimental-flag', () => {
expect(buildOutput).toMatchInlineSnapshot(` expect(buildOutput).toMatchInlineSnapshot(`
" "
./app/page.tsx ./app/page.tsx
Error: x To use "use cache", please enable the experimental feature flag "useCache" in your Next.js config. Error: x To use "use cache", please enable the feature flag \`experimental.cacheComponents\` in your Next.js config.
| |
| Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage | Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
...@@ -120,7 +120,7 @@ describe('use-cache-without-experimental-flag', () => { ...@@ -120,7 +120,7 @@ describe('use-cache-without-experimental-flag', () => {
) )
} else { } else {
expect(errorDescription).toMatchInlineSnapshot( expect(errorDescription).toMatchInlineSnapshot(
`" x To use "use cache", please enable the experimental feature flag "useCache" in your Next.js config."` `" x To use "use cache", please enable the feature flag \`experimental.cacheComponents\` in your Next.js config."`
) )
} }
...@@ -134,7 +134,7 @@ describe('use-cache-without-experimental-flag', () => { ...@@ -134,7 +134,7 @@ describe('use-cache-without-experimental-flag', () => {
3 | export default async function Page() { 3 | export default async function Page() {
4 | return <p>hello world</p> 4 | return <p>hello world</p>
To use "use cache", please enable the experimental feature flag "useCache" in your Next.js config. To use "use cache", please enable the feature flag \`experimental.cacheComponents\` in your Next.js config.
Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage" Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage"
`) `)
...@@ -142,7 +142,7 @@ describe('use-cache-without-experimental-flag', () => { ...@@ -142,7 +142,7 @@ describe('use-cache-without-experimental-flag', () => {
expect(errorSource).toMatchInlineSnapshot(` expect(errorSource).toMatchInlineSnapshot(`
"./app/page.tsx "./app/page.tsx
× Module build failed: × Module build failed:
╰─▶ × Error: x To use "use cache", please enable the experimental feature flag "useCache" in your Next.js config. ╰─▶ × Error: x To use "use cache", please enable the feature flag \`experimental.cacheComponents\` in your Next.js config.
│ | │ |
│ | Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage │ | Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
│ │
...@@ -158,7 +158,7 @@ describe('use-cache-without-experimental-flag', () => { ...@@ -158,7 +158,7 @@ describe('use-cache-without-experimental-flag', () => {
} else { } else {
expect(errorSource).toMatchInlineSnapshot(` expect(errorSource).toMatchInlineSnapshot(`
"./app/page.tsx "./app/page.tsx
Error: x To use "use cache", please enable the experimental feature flag "useCache" in your Next.js config. Error: x To use "use cache", please enable the feature flag \`experimental.cacheComponents\` in your Next.js config.
| |
| Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage | Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment