Unverified Commit 81bdd9cb authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: add Turbopack experimental config references (#99723)

## Summary

- add API references for `turbopackGc`, `turbopackLazyDynamicImports`,
`turbopackLazyDynamicImportsSSR`, and `turbopackPluginRuntimeStrategy`
- document each option’s defaults, supported values, runtime behavior,
and relevant limitations
- cross-link related Turbopack configuration options

## Verification

- Verified configuration types and defaults against the current config
source and Turbopack tests
- `pnpm prettier --with-node-modules --ignore-path .prettierignore
--check <new-docs>`
- `npx eslint --config eslint.config.mjs --fix <new-docs>`

<!-- NEXT_JS_LLM -->

---------
Co-authored-by: 's avatarNiklas Mischkulnig <4586894+mischnic@users.noreply.github.com>
parent fd9c5e93
......@@ -2,6 +2,9 @@
title: Turbopack FileSystem Caching
nav_title: turbopackFileSystemCache
description: Learn how to enable and configure FileSystem Caching for Turbopack builds
related:
links:
- app/api-reference/config/next-config-js/turbopackGc
---
## Usage
......
---
title: turbopackGc
description: Configure Turbopack to remove unreachable work from memory and the persistent cache.
version: experimental
related:
links:
- app/api-reference/config/next-config-js/turbopackFileSystemCache
- app/api-reference/config/next-config-js/turbopackMemoryEviction
---
The `experimental.turbopackGc` option enables garbage collection for Turbopack's in-memory and [persistent caches](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache).
```ts filename="next.config.ts" switcher highlight={5}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
turbopackGc: true,
},
}
export default nextConfig
```
```js filename="next.config.js" switcher highlight={4}
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
turbopackGc: true,
},
}
module.exports = nextConfig
```
## Reference
`turbopackGc` defaults to `false` and accepts a boolean or an object:
| Value | Description |
| -------------------------------- | ---------------------------------------------------------------------------- |
| `false` | Disables garbage collection. |
| `true` | Enables garbage collection with the default timings. |
| `{ minProgressMs?, rootTtlMs? }` | Enables garbage collection and overrides one or more of the default timings. |
When enabled, Turbopack removes unreachable work from memory and its persistent cache. The option applies to both `next dev` and `next build` when they use Turbopack.
> **Good to know:**
>
> - Garbage collection requires the [Turbopack FileSystem Cache](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache). The option has no effect when the cache is disabled for the current command.
> - In long-running read-write sessions, Turbopack disables garbage collection when [`turbopackMemoryEviction`](/docs/app/api-reference/config/next-config-js/turbopackMemoryEviction) is set to `false`.
### Options
The object form accepts the following properties:
| Property | Type | Default | Description |
| --------------- | --------------------- | -------------------- | --------------------------------------------------------------------------------- |
| `minProgressMs` | Non-negative `number` | `100` | Minimum time a garbage collection pass runs before it honors an interruption. |
| `rootTtlMs` | Non-negative `number` | `259200000` (3 days) | Time a garbage collection root can remain unanchored before Turbopack removes it. |
The following configuration lets a garbage collection pass run for at least 200 milliseconds before yielding and expires unanchored roots after one day:
```ts filename="next.config.ts" switcher highlight={5-8}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
turbopackGc: {
minProgressMs: 200,
rootTtlMs: 24 * 60 * 60 * 1000,
},
},
}
export default nextConfig
```
```js filename="next.config.js" switcher highlight={4-7}
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
turbopackGc: {
minProgressMs: 200,
rootTtlMs: 24 * 60 * 60 * 1000,
},
},
}
module.exports = nextConfig
```
## Version History
| Version | Changes |
| --------- | ------------------------------------------------------ |
| `v16.4.0` | `experimental.turbopackGc` configuration option added. |
---
title: turbopackLazyDynamicImports
description: Compile client-side dynamic imports when they are first requested during development.
version: experimental
related:
links:
- app/api-reference/config/next-config-js/turbopackLazyDynamicImportsSSR
---
The `experimental.turbopackLazyDynamicImports` option defers compiling client-side dynamic `import()` targets until the browser first requests them during `next dev`.
```ts filename="next.config.ts" switcher highlight={5}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
turbopackLazyDynamicImports: true,
},
}
export default nextConfig
```
```js filename="next.config.js" switcher highlight={4}
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
turbopackLazyDynamicImports: true,
},
}
module.exports = nextConfig
```
## How it works
With `turbopackLazyDynamicImports` enabled, Turbopack waits to compile the target of a client-side dynamic `import()` until the browser requests its chunk. Code that the application never imports remains uncompiled during the development session.
For example, the module in this Client Component is compiled when the visitor selects the button:
```tsx filename="app/greeting-button.tsx" switcher
'use client'
import { useState } from 'react'
export function GreetingButton() {
const [message, setMessage] = useState('')
async function showGreeting() {
const { getGreeting } = await import('./get-greeting')
setMessage(getGreeting('Ada'))
}
return (
<>
<button onClick={showGreeting}>Show greeting</button>
<p>{message}</p>
</>
)
}
```
```jsx filename="app/greeting-button.js" switcher
'use client'
import { useState } from 'react'
export function GreetingButton() {
const [message, setMessage] = useState('')
async function showGreeting() {
const { getGreeting } = await import('./get-greeting')
setMessage(getGreeting('Ada'))
}
return (
<>
<button onClick={showGreeting}>Show greeting</button>
<p>{message}</p>
</>
)
}
```
> **Good to know:**
>
> - The option defaults to `false` and only affects Turbopack during `next dev`. It does not change production builds.
> - Errors in a deferred module appear when Turbopack first compiles that module.
> - Some [`next/dynamic`](/docs/app/guides/lazy-loading#nextdynamic) targets are still compiled eagerly.
> - To defer dynamic imports reached while rendering Client Components on the server, use [`turbopackLazyDynamicImportsSSR`](/docs/app/api-reference/config/next-config-js/turbopackLazyDynamicImportsSSR).
## Version History
| Version | Changes |
| --------- | ---------------------------------------------------------------------- |
| `v16.4.0` | `experimental.turbopackLazyDynamicImports` configuration option added. |
---
title: turbopackLazyDynamicImportsSSR
description: Compile dynamic imports when server rendering first reaches them during development.
version: experimental
related:
links:
- app/api-reference/config/next-config-js/turbopackLazyDynamicImports
---
The `experimental.turbopackLazyDynamicImportsSSR` option defers compiling dynamic imports until server rendering first reaches them during `next dev`.
```ts filename="next.config.ts" switcher highlight={5}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
turbopackLazyDynamicImportsSSR: true,
},
}
export default nextConfig
```
```js filename="next.config.js" switcher highlight={4}
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
turbopackLazyDynamicImportsSSR: true,
},
}
module.exports = nextConfig
```
## How it works
Client Components can use [`lazy`](https://react.dev/reference/react/lazy) to load a component dynamically. With `turbopackLazyDynamicImportsSSR` enabled, Turbopack compiles the imported component when a server render first reaches it. A target that is not rendered remains uncompiled.
In the following example, Turbopack compiles `Preview` when `showPreview` is `true` during server rendering:
```tsx filename="app/preview.tsx" switcher
'use client'
import { lazy } from 'react'
const Preview = lazy(() => import('./preview-panel'))
export function MaybePreview({ showPreview }: { showPreview: boolean }) {
return showPreview ? <Preview /> : null
}
```
```jsx filename="app/preview.js" switcher
'use client'
import { lazy } from 'react'
const Preview = lazy(() => import('./preview-panel'))
export function MaybePreview({ showPreview }) {
return showPreview ? <Preview /> : null
}
```
> **Good to know:**
>
> - The option defaults to `false` and only affects the Node.js runtime with Turbopack during `next dev`. It does not change production builds.
> - To defer client-side dynamic imports until the browser requests them, use [`turbopackLazyDynamicImports`](/docs/app/api-reference/config/next-config-js/turbopackLazyDynamicImports).
## Version History
| Version | Changes |
| --------- | ------------------------------------------------------------------------- |
| `v16.4.0` | `experimental.turbopackLazyDynamicImportsSSR` configuration option added. |
---
title: turbopackPluginRuntimeStrategy
description: Choose how Turbopack runs Node.js evaluation for webpack loaders, Babel, and PostCSS.
version: experimental
related:
links:
- app/api-reference/config/next-config-js/turbopack
---
The `experimental.turbopackPluginRuntimeStrategy` option chooses whether Turbopack runs Node.js evaluation in child processes or worker threads.
```ts filename="next.config.ts" switcher highlight={5}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
turbopackPluginRuntimeStrategy: 'workerThreads',
},
}
export default nextConfig
```
```js filename="next.config.js" switcher highlight={4}
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
turbopackPluginRuntimeStrategy: 'workerThreads',
},
}
module.exports = nextConfig
```
This runtime executes Node.js-based tools, including [webpack loaders](/docs/app/api-reference/config/next-config-js/turbopack#configuring-webpack-loaders), Babel, and PostCSS.
## Reference
| Value | Default | Description |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `'childProcesses'` | Yes | Runs Node.js evaluation in a pool of child processes and communicates with them over sockets. |
| `'workerThreads'` | No | Runs Node.js evaluation in worker threads within the Next.js process. This can reduce memory and CPU overhead compared with a child process pool. |
| `'forceWorkerThreads'` | No | Uses worker threads even when the current Node.js version is affected by the worker-thread teardown issue described below. This can abort the process. |
## Node.js compatibility
On Node.js 24.13.1 and newer, a [Node.js worker-thread teardown issue](https://github.com/nodejs/node/issues/65100) can abort the process when a worker exits while a native addon has a live Node-API thread-safe function.
When `turbopackPluginRuntimeStrategy` is set to `'workerThreads'` on an affected Node.js version, Next.js prints a warning and falls back to `'childProcesses'`. Set `'forceWorkerThreads'` to bypass the fallback at the risk of aborting the process.
## Version History
| Version | Changes |
| --------- | ------------------------------------------------------------------------- |
| `v16.4.0` | `experimental.turbopackPluginRuntimeStrategy` configuration option added. |
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