Unverified Commit 4b85c8b6 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

Warn when Partial Prefetching is not configured (#99452)

## Summary

Warn when `cacheComponents` is enabled without an explicit
`partialPrefetching` setting. The warning asks users to choose `true` or
`false`, explains that `false` is only for incremental migration, and
links to the migration guide.

Document that new apps should enable both options, while existing apps
should migrate Cache Components and Partial Prefetching incrementally.
Both features will be enabled everywhere in the next major release, and
the old configuration options will be removed.

## Example output

```text
⚠ `cacheComponents` is enabled without a corresponding `partialPrefetching` option. Set `partialPrefetching` to either `true` or `false`.

The only reason to set `partialPrefetching` to `false` is if you're migrating an older Cache Components app. The initial release of Cache Components did not include Partial Prefetching. New projects should enable both Cache Components and Partial Prefetching.

Both Cache Components and Partial Prefetching will be enabled everywhere in the next major release, and the old configurations will be removed.

Learn more: https://nextjs.org/docs/app/guides/adopting-partial-prefetching
```

## Verification

- `pnpm jest packages/next/src/server/config.test.ts --runInBand` (22
tests passed)
- Prettier and ESLint on all changed files
- Production test matrix left to CI

<!-- NEXT_JS_LLM -->

---------
Co-authored-by: 's avatarClaude Opus 5.5 <noreply@anthropic.com>
parent 45f4b19c
......@@ -17,15 +17,16 @@ Caching is a technique for storing the result of data fetching and other computa
## Enabling Cache Components
New App Router apps created with the recommended [`create-next-app`](/docs/app/api-reference/cli/create-next-app) defaults already have Cache Components enabled.
New App Router apps created with the recommended [`create-next-app`](/docs/app/api-reference/cli/create-next-app) defaults already have Cache Components and Partial Prefetching enabled.
To enable it in an existing or manually created app, add the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) option to your Next config file:
To enable it in an existing or manually created app, add the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) and [`partialPrefetching`](/docs/app/api-reference/config/next-config-js/partialPrefetching) options to your Next config file:
```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfig
......@@ -35,11 +36,14 @@ export default nextConfig
/** @type {import('next').NextConfig} */
const nextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
module.exports = nextConfig
```
Set `partialPrefetching` explicitly. Leaving it unset logs a warning, because the first release of Cache Components did not include Partial Prefetching. Set it to `false` only while [migrating an app that adopted Cache Components before Partial Prefetching](/docs/app/guides/adopting-partial-prefetching). Both features will be enabled everywhere in the next major release, and the options will be removed.
> **Good to know:** When Cache Components is enabled, `GET` Route Handlers follow the same prerendering model as pages. See [Route Handlers with Cache Components](/docs/app/getting-started/route-handlers#with-cache-components) for details.
## Usage
......
......@@ -69,6 +69,8 @@ export default nextConfig
After enabling the flag, links using the default behavior, `prefetch="auto"`, or `prefetch={true}` prefetch the destination's App Shell. A link with `prefetch={true}` can also resolve cached URL-specific content, but it no longer includes uncached dynamic content from the legacy full prefetch. New projects can enable the flag without this audit because they have no legacy full prefetches to migrate.
> **Good to know**: When `cacheComponents` is enabled without a `partialPrefetching` value, Next.js logs a warning asking you to set it to `true` or `false`. Set `false` only to keep the previous prefetch behavior while you work through this guide. Both features will be enabled everywhere in the next major release, and the options will be removed.
## What changes for `<Link>`
| `<Link>` prop | Before (Cache Components default) | After Partial Prefetching |
......
......@@ -13,18 +13,21 @@ Cache Components enables component and function-level caching using the [`use ca
## Usage
To enable the `cacheComponents` flag, set it to `true` in your `next.config.ts` file:
To enable the `cacheComponents` flag, set it to `true` in your `next.config.ts` file, together with [`partialPrefetching`](/docs/app/api-reference/config/next-config-js/partialPrefetching):
```ts filename="next.config.ts"
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfig
```
Set `partialPrefetching` explicitly. Leaving it unset logs a warning, because the first release of Cache Components did not include Partial Prefetching. Set it to `false` only while [migrating an app that adopted Cache Components before Partial Prefetching](/docs/app/guides/adopting-partial-prefetching). Both features will be enabled everywhere in the next major release, and the options will be removed.
> **Good to know**: Cache Components requires the Node.js runtime. Migrate any routes that set the deprecated `runtime = 'edge'` export, and note that other server-side JavaScript runtimes are not guaranteed to work. See [Migrating to Cache Components](/docs/app/guides/migrating-to-cache-components#runtime--edge).
When `cacheComponents` is enabled, you can use the following cache functions and configurations:
......
......@@ -37,10 +37,12 @@ module.exports = {
## Reference
| Value | Description |
| ------- | ------------------------------------------- |
| `true` | Enables Partial Prefetching across the app. |
| `false` | Default. No change to prefetch behavior. |
| Value | Description |
| ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `true` | Enables Partial Prefetching across the app. |
| `false` | Keeps the previous prefetch behavior, for apps that adopted Cache Components before Partial Prefetching was available. |
Leaving the option unset behaves like `false` and logs a warning when `cacheComponents` is enabled. Both features will be enabled everywhere in the next major release, and the options will be removed.
## How prefetches resolve
......
......@@ -292,6 +292,55 @@ describe('loadConfig', () => {
})
})
describe('partialPrefetching validation', () => {
const warning = [
'⚠ `cacheComponents` is enabled without a corresponding `partialPrefetching` option. Set `partialPrefetching` to either `true` or `false`.',
"The only reason to set `partialPrefetching` to `false` is if you're migrating an older Cache Components app. The initial release of Cache Components did not include Partial Prefetching. New projects should enable both Cache Components and Partial Prefetching.",
'Both Cache Components and Partial Prefetching will be enabled everywhere in the next major release, and the old configurations will be removed.',
'Learn more: https://nextjs.org/docs/app/guides/adopting-partial-prefetching',
].join('\n\n')
afterEach(() => {
jest.restoreAllMocks()
})
it('warns when cacheComponents is enabled without partialPrefetching', async () => {
const consoleWarn = jest
.spyOn(console, 'warn')
.mockImplementation(() => {})
await loadConfig(PHASE_PRODUCTION_BUILD, __dirname, {
customConfig: {
cacheComponents: true,
},
silent: false,
})
expect(consoleWarn).toHaveBeenCalledWith(warning)
})
it.each([true, false])(
'does not warn when partialPrefetching is explicitly set to %s',
async (partialPrefetching) => {
const consoleWarn = jest
.spyOn(console, 'warn')
.mockImplementation(() => {})
await loadConfig(PHASE_PRODUCTION_BUILD, __dirname, {
customConfig: {
cacheComponents: true,
partialPrefetching,
},
silent: false,
})
expect(consoleWarn).not.toHaveBeenCalledWith(
expect.stringContaining(warning)
)
}
)
})
describe('experimental.cssChunking bundler validation', () => {
it('should not validate `cssChunking` during `next info`', async () => {
const result = await loadConfig(PHASE_INFO, __dirname, {
......
......@@ -645,6 +645,23 @@ function assignDefaultsAndValidate(
)
}
// TODO: Before Next.js 17, also warn when `partialPrefetching` is `false`
// so apps can migrate before both features are enabled together by default.
if (
result.cacheComponents &&
result.partialPrefetching === undefined &&
!silent
) {
Log.warnOnce(
[
'`cacheComponents` is enabled without a corresponding `partialPrefetching` option. Set `partialPrefetching` to either `true` or `false`.',
"The only reason to set `partialPrefetching` to `false` is if you're migrating an older Cache Components app. The initial release of Cache Components did not include Partial Prefetching. New projects should enable both Cache Components and Partial Prefetching.",
'Both Cache Components and Partial Prefetching will be enabled everywhere in the next major release, and the old configurations will be removed.',
'Learn more: https://nextjs.org/docs/app/guides/adopting-partial-prefetching',
].join('\n\n')
)
}
if (result.experimental.ppr) {
throw new HardDeprecatedConfigError(
`\`experimental.ppr\` has been merged into \`cacheComponents\`. The Partial Prerendering feature is still available, but is now enabled via \`cacheComponents\`. Please update your ${configFileName} accordingly.`
......
......@@ -3,6 +3,7 @@
*/
const nextConfig = {
cacheComponents: true,
partialPrefetching: false,
experimental: {
instantInsights: {
validationLevel: 'manual-warning',
......
......@@ -3,6 +3,7 @@
*/
const nextConfig = {
cacheComponents: true,
partialPrefetching: !!process.env.__NEXT_PARTIAL_PREFETCHING,
experimental: {
instantInsights: {
validationLevel: 'manual-warning',
......
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