Unverified Commit 96a33793 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: record API stabilization across Next.js 16 releases (#99420)

## Summary

Fill gaps in API reference history so readers can tell which Next.js 16
release stabilized an API or renamed its experimental form.

- **16.0.0:** Record stabilization of `cacheLife()`, `cacheTag()`, `use
cache`, the caching configuration options, React Compiler support, and
Turbopack production builds. Add the missing `enablePrerenderSourceMaps`
reference, shared with the Pages Router, documenting its current default
and promotion out of `experimental`.
- **16.2.0:** Record the promotion of `adapterPath` to a stable,
top-level option.
- **16.3.0:** Replace the `v16.x.x` placeholders for the `instant` and
`prefetch` route exports with their stabilization version and previous
names.
- **16.4.0:** Clarify that the new `prefetch()` and `navigation()`
functions replace names used in earlier canaries.

The `catchError` and `retry` histories already correctly record
introduction in 16.2.0 and stabilization in 16.3.0, so they are
unchanged.

## Verification

- Checked the 16.0 release and upgrade guides, PR #84877, and the
configuration definitions/migrations in the v15.5.0 and v16.0.0 tags.
- Checked the route exports against the v16.2.0/v16.3.0 source and
stabilization commits #94578 and #94571; checked the function renames
against #99241.
- Checked the new source-map reference against the current config
default and prerender worker implementation.
- Prettier and diff checks passed. Documentation only; no runtime code
changed.

<!-- NEXT_JS_LLM -->
parent 7f3821a9
...@@ -775,7 +775,7 @@ Learn how to [configure caching](/docs/app/guides/self-hosting#caching-and-isr) ...@@ -775,7 +775,7 @@ Learn how to [configure caching](/docs/app/guides/self-hosting#caching-and-isr)
## Version History ## Version History
| Version | Changes | | Version | Changes |
| --------- | ----------------------------------------------------------- | | --------- | -------------------------------------------------------------------------- |
| `v16.0.0` | `"use cache"` is enabled with the Cache Components feature. | | `v16.0.0` | `"use cache"` stabilized and is enabled with the Cache Components feature. |
| `v15.0.0` | `"use cache"` is introduced as an experimental feature. | | `v15.0.0` | `"use cache"` is introduced as an experimental feature. |
...@@ -167,6 +167,6 @@ export const instant: InstantConfig = true ...@@ -167,6 +167,6 @@ export const instant: InstantConfig = true
## Version History ## Version History
| Version | Changes | | Version | Changes |
| --------- | --------------------------------------------------- | | --------- | ---------------------------------------------------------------------------------- |
| `v16.x.x` | `instant` export introduced (Cache Components only) | | `v16.3.0` | `instant` export stabilized, replacing `unstable_instant` (Cache Components only). |
...@@ -79,6 +79,6 @@ export const prefetch: Prefetch = 'partial' ...@@ -79,6 +79,6 @@ export const prefetch: Prefetch = 'partial'
## Version History ## Version History
| Version | Changes | | Version | Changes |
| --------- | ---------------------------------------------------- | | --------- | ------------------------------------------------------------------------------------ |
| `v16.x.x` | `prefetch` export introduced (Cache Components only) | | `v16.3.0` | `prefetch` export stabilized, replacing `unstable_prefetch` (Cache Components only). |
...@@ -596,3 +596,11 @@ async function getPostContent(slug: string) { ...@@ -596,3 +596,11 @@ async function getPostContent(slug: string) {
return post.data return post.data
} }
``` ```
## Version History
| Version | Changes |
| --------- | -------------------------------------------------------- |
| `v16.0.0` | `cacheLife` stabilized. `unstable_cacheLife` deprecated. |
See the [Next.js 16 upgrade guide](/docs/app/guides/upgrading/version-16#cachelife-and-cachetag) to update imports from `unstable_cacheLife` to `cacheLife`.
...@@ -217,3 +217,11 @@ export async function updateBookings() { ...@@ -217,3 +217,11 @@ export async function updateBookings() {
revalidateTag('bookings-data', 'max') revalidateTag('bookings-data', 'max')
} }
``` ```
## Version History
| Version | Changes |
| --------- | ------------------------------------------------------ |
| `v16.0.0` | `cacheTag` stabilized. `unstable_cacheTag` deprecated. |
See the [Next.js 16 upgrade guide](/docs/app/guides/upgrading/version-16#cachelife-and-cachetag) to update imports from `unstable_cacheTag` to `cacheTag`.
...@@ -190,6 +190,6 @@ A `Promise<void>`. It is not meant to be consumed. ...@@ -190,6 +190,6 @@ A `Promise<void>`. It is not meant to be consumed.
## Version History ## Version History
| Version | Changes | | Version | Changes |
| --------- | ------------------- | | --------- | -------------------------------------------------------------------------------------------------- |
| `v16.4.0` | `navigation` added. | | `v16.4.0` | `navigation` introduced, replacing the `unstable_navigation` name used in earlier canary releases. |
...@@ -171,6 +171,6 @@ A `Promise<void>`. It is not meant to be consumed. ...@@ -171,6 +171,6 @@ A `Promise<void>`. It is not meant to be consumed.
## Version History ## Version History
| Version | Changes | | Version | Changes |
| --------- | ----------------- | | --------- | ---------------------------------------------------------------------------------------------- |
| `v16.4.0` | `prefetch` added. | | `v16.4.0` | `prefetch` introduced, replacing the `unstable_prefetch` name used in earlier canary releases. |
...@@ -77,3 +77,9 @@ See [Routing Information](/docs/app/api-reference/adapters/routing-information). ...@@ -77,3 +77,9 @@ See [Routing Information](/docs/app/api-reference/adapters/routing-information).
## Use Cases ## Use Cases
See [Use Cases](/docs/app/api-reference/adapters/use-cases). See [Use Cases](/docs/app/api-reference/adapters/use-cases).
## Version History
| Version | Changes |
| --------- | --------------------------------------------------------------------------------------------------------- |
| `v16.2.0` | `adapterPath` stabilized and moved from `experimental.adapterPath` to the top-level `adapterPath` option. |
...@@ -59,6 +59,6 @@ Some UI patterns behave differently when components stay mounted instead of unmo ...@@ -59,6 +59,6 @@ Some UI patterns behave differently when components stay mounted instead of unmo
## Version History ## Version History
| Version | Change | | Version | Change |
| ------- | --------------------------------------------------------------------------------------------------------------------------------- | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 16.0.0 | `cacheComponents` introduced. This flag controls the `ppr`, `useCache`, and `dynamicIO` flags as a single, unified configuration. | | 16.0.0 | `cacheComponents` stabilized and moved from `experimental.cacheComponents` to the top-level `cacheComponents` option. This flag controls the `ppr`, `useCache`, and `dynamicIO` flags as a single, unified configuration. |
...@@ -551,6 +551,6 @@ module.exports = { ...@@ -551,6 +551,6 @@ module.exports = {
## Version History ## Version History
| Version | Changes | | Version | Changes |
| --------- | --------------------------- | | --------- | --------------------------------------------------------------------------------------------------------------- |
| `v16.0.0` | `cacheHandlers` introduced. | | `v16.0.0` | `cacheHandlers` stabilized and moved from `experimental.cacheHandlers` to the top-level `cacheHandlers` option. |
...@@ -83,3 +83,9 @@ The configuration object has key values with the following format: ...@@ -83,3 +83,9 @@ The configuration object has key values with the following format:
| `stale` | `number` | Duration the client should cache a value without checking the server. | Optional | | `stale` | `number` | Duration the client should cache a value without checking the server. | Optional |
| `revalidate` | `number` | Frequency at which the cache should refresh on the server; stale values may be served while revalidating. | Optional | | `revalidate` | `number` | Frequency at which the cache should refresh on the server; stale values may be served while revalidating. | Optional |
| `expire` | `number` | Maximum duration for which a value can remain stale before switching to dynamic. | Optional - Must be longer than `revalidate` | | `expire` | `number` | Maximum duration for which a value can remain stale before switching to dynamic. | Optional - Must be longer than `revalidate` |
## Version History
| Version | Changes |
| --------- | --------------------------------------------------------------------------------------------------- |
| `v16.0.0` | `cacheLife` stabilized and moved from `experimental.cacheLife` to the top-level `cacheLife` option. |
---
title: enablePrerenderSourceMaps
description: Enable source maps for errors during prerendering in next build.
related:
links:
- app/guides/memory-usage
- app/api-reference/config/next-config-js/productionBrowserSourceMaps
---
The `enablePrerenderSourceMaps` option lets Node.js use existing source maps during the prerender phase of `next build`. When source maps are available, error stack traces point to the original source code. It defaults to `true`.
This option does not generate source maps. Webpack does not generate server source maps by default. To generate them when investigating prerender errors, use [`next build --debug-prerender`](/docs/app/api-reference/cli/next#debugging-prerender-errors).
To disable it, set `enablePrerenderSourceMaps` to `false`:
```ts filename="next.config.ts" switcher highlight={4}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
enablePrerenderSourceMaps: false,
}
export default nextConfig
```
```js filename="next.config.js" switcher highlight={3}
/** @type {import('next').NextConfig} */
const nextConfig = {
enablePrerenderSourceMaps: false,
}
module.exports = nextConfig
```
## Reference
| Option | Type | Default |
| --------------------------- | --------- | ------- |
| `enablePrerenderSourceMaps` | `boolean` | `true` |
Disabling source maps during prerendering can reduce [build memory usage](/docs/app/guides/memory-usage#disable-source-maps), but makes prerendering errors harder to debug.
## Version History
| Version | Changes |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `v16.3.0` | The default changed to `true`, regardless of whether `cacheComponents` is enabled. |
| `v16.0.0` | `enablePrerenderSourceMaps` moved from `experimental.enablePrerenderSourceMaps` to the top-level `enablePrerenderSourceMaps` option. |
...@@ -96,3 +96,9 @@ export default function Page() { ...@@ -96,3 +96,9 @@ export default function Page() {
``` ```
> **Note:** You can also use the `"use no memo"` directive from React for the opposite effect, to opt-out a component or hook. > **Note:** You can also use the `"use no memo"` directive from React for the opposite effect, to opt-out a component or hook.
## Version History
| Version | Changes |
| --------- | --------------------------------------------------------------------------------------------------------------- |
| `v16.0.0` | `reactCompiler` stabilized and moved from `experimental.reactCompiler` to the top-level `reactCompiler` option. |
...@@ -519,9 +519,9 @@ Turbopack is a **Rust-based**, **incremental** bundler designed to make local de ...@@ -519,9 +519,9 @@ Turbopack is a **Rust-based**, **incremental** bundler designed to make local de
## Version Changes ## Version Changes
| Version | Changes | | Version | Changes |
| --------- | ------------------------------------------------------------------------------------------------------------------ | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v16.0.0` | Turbopack becomes the default bundler for Next.js. Automatic support for Babel when a configuration file is found. | | `v16.0.0` | Turbopack support for `build` is stable, and Turbopack becomes the default bundler for Next.js. Automatic support for Babel when a configuration file is found. |
| `v15.5.0` | Turbopack support for `build` beta | | `v15.5.0` | Turbopack support for `build` beta |
| `v15.3.0` | Experimental support for `build` | | `v15.3.0` | Experimental support for `build` |
| `v15.0.0` | Turbopack for `dev` stable | | `v15.0.0` | Turbopack for `dev` stable |
---
title: enablePrerenderSourceMaps
description: Enable source maps for errors during prerendering in next build.
source: app/api-reference/config/next-config-js/enablePrerenderSourceMaps
---
{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
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