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) {
span,
formatdoc! {
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) {
span,
formatdoc! {
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
"#
......
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]
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]
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
|
......
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
|
......
......@@ -6,7 +6,6 @@ related:
title: Related
description: View related API references.
links:
- app/api-reference/config/next-config-js/useCache
- app/api-reference/config/next-config-js/cacheComponents
- app/api-reference/config/next-config-js/cacheLife
- app/api-reference/functions/cacheTag
......@@ -18,14 +17,14 @@ The `use cache` directive allows you to mark a route, React component, or a func
## 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
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
useCache: true,
cacheComponents: true,
},
}
......@@ -36,15 +35,13 @@ export default nextConfig
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
useCache: true,
cacheComponents: true,
},
}
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:
```tsx
......
......@@ -809,5 +809,14 @@
"808": "Invalid binary HMR message: insufficient data (expected %s bytes, got %s)",
"809": "Invalid binary HMR message of type %s",
"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 { workUnitAsyncStorage } from '../app-render/work-unit-async-storage.external'
......@@ -87,7 +88,7 @@ function validateCacheLife(profile: CacheLife) {
export function cacheLife(profile: CacheLifeProfiles | CacheLife): void {
if (!process.env.__NEXT_USE_CACHE) {
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 {
case 'unstable-cache':
case undefined:
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 'private-cache':
......@@ -116,13 +117,11 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void {
const workStore = workAsyncStorage.getStore()
if (!workStore) {
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) {
throw new Error(
'cacheLifeProfiles should always be provided. This is a bug in Next.js.'
)
throw new InvariantError('`cacheLifeProfiles` should always be provided.')
}
// TODO: This should be globally available and not require an AsyncLocalStorage.
......@@ -130,12 +129,12 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void {
if (configuredProfile === undefined) {
if (workStore.cacheLifeProfiles[profile.trim()]) {
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?`
)
}
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' +
' experimental: {\n' +
' cacheLife: {\n' +
......@@ -152,7 +151,7 @@ export function cacheLife(profile: CacheLifeProfiles | CacheLife): void {
Array.isArray(profile)
) {
throw new Error(
'Invalid cacheLife() option. Either pass a profile name or object.'
'Invalid `cacheLife()` option. Either pass a profile name or object.'
)
} else {
validateCacheLife(profile)
......
......@@ -4,7 +4,7 @@ import { validateTags } from '../lib/patch-fetch'
export function cacheTag(...tags: string[]): void {
if (!process.env.__NEXT_USE_CACHE) {
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 {
case 'unstable-cache':
case undefined:
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 'private-cache':
......@@ -29,7 +29,7 @@ export function cacheTag(...tags: string[]): void {
workUnitStore satisfies never
}
const validTags = validateTags(tags, 'cacheTag()')
const validTags = validateTags(tags, '`cacheTag()`')
if (!workUnitStore.tags) {
workUnitStore.tags = validTags
......
......@@ -41,7 +41,7 @@ describe('use-cache-unknown-cache-kind', () => {
3 | export default async function Page() {
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', () => {
"
./app/page.tsx
× 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 | 'use cache: custom'
......@@ -75,7 +75,7 @@ describe('use-cache-unknown-cache-kind', () => {
expect(buildOutput).toMatchInlineSnapshot(`
"
./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 | 'use cache: custom'
......@@ -124,7 +124,7 @@ describe('use-cache-unknown-cache-kind', () => {
)
} else {
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', () => {
3 | export default async function Page() {
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) {
expect(errorSource).toMatchInlineSnapshot(`
"./app/page.tsx
× 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 | 'use cache: custom'
......@@ -158,7 +158,7 @@ describe('use-cache-unknown-cache-kind', () => {
} else {
expect(errorSource).toMatchInlineSnapshot(`
"./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 | 'use cache: custom'
......
......@@ -42,7 +42,7 @@ describe('use-cache-without-experimental-flag', () => {
3 | export default async function Page() {
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
......@@ -56,7 +56,7 @@ describe('use-cache-without-experimental-flag', () => {
"
./app/page.tsx
× 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
│
......@@ -80,7 +80,7 @@ describe('use-cache-without-experimental-flag', () => {
expect(buildOutput).toMatchInlineSnapshot(`
"
./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
......@@ -120,7 +120,7 @@ describe('use-cache-without-experimental-flag', () => {
)
} else {
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', () => {
3 | export default async function Page() {
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"
`)
......@@ -142,7 +142,7 @@ describe('use-cache-without-experimental-flag', () => {
expect(errorSource).toMatchInlineSnapshot(`
"./app/page.tsx
× 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
│
......@@ -158,7 +158,7 @@ describe('use-cache-without-experimental-flag', () => {
} else {
expect(errorSource).toMatchInlineSnapshot(`
"./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
......
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