Unverified Commit d726fe30 authored by Will Binns-Smith's avatar Will Binns-Smith Committed by GitHub

Turbopack experimental fields docs and schema (#45560)

This adds:
- Documentation for Turbopack experimental fields `turbopackLoaders` and `resolveAlias` to the API reference site.
- Typings and schema for the above Turbopack experimental options

Test Plan: 
- `pnpm build`, updated an example to use TypeScript for its Next.js config, and verified the config passed with matching shapes and failed with mismatching shapes.
parent 53c2ae87
---
description: Configure Next.js with Turbopack-specific options
---
# Turbopack-specific options (experimental)
> **Warning**: These features are experimental and will only work with `next --turbo`.
## webpack loaders
Currently, Turbopack supports a subset of webpack's loader API, allowing you to use some webpack loaders to transform code in Turbopack.
To configure loaders, add the names of the loaders you've installed and any options in `next.config.js`, mapping file extensions to a list of loaders:
```js
module.exports = {
experimental: {
turbo: {
loaders: {
// Option format
'.md': [
{
loader: '@mdx-js/loader',
options: {
format: 'md',
},
},
],
// Option-less format
'.mdx': '@mdx-js/loader',
},
},
},
}
```
Then, given the above configuration, you can use transformed code from your app:
```js
import MyDoc from './my-doc.mdx'
export default function Home() {
return <MyDoc />
}
```
## Resolve Alias
Through `next.config.js`, Turbopack can be configured to modify module resolution through aliases, similar to webpack's [`resolve.alias`](https://webpack.js.org/configuration/resolve/#resolvealias) configuration.
To configure resolve aliases, map imported patterns to their new destination in `next.config.js`:
```js
module.exports = {
experimental: {
turbo: {
resolveAlias: {
underscore: 'lodash',
mocha: { browser: 'mocha/browser-entry.js' },
},
},
},
}
```
This aliases imports of the `underscore` package to the `lodash` package. In other words, `import underscore from 'underscore'` will load the `lodash` module instead of `underscore`.
Turbopack also supports conditional aliasing through this field, similar to Node.js's [conditional exports](https://nodejs.org/docs/latest-v18.x/api/packages.html#conditional-exports). At the moment only the `browser` condition is supported. In the case above, imports of the `mocha` module will be aliased to `mocha/browser-entry.js` when Turbopack targets browser environments.
For more information and guidance for how to migrate your app to Turbopack from webpack, see [Turbopack's documentation on webpack compatibility](https://turbo.build/pack/docs/migrating-from-webpack).
...@@ -571,6 +571,10 @@ ...@@ -571,6 +571,10 @@
{ {
"title": "Build indicator", "title": "Build indicator",
"path": "/docs/api-reference/next.config.js/build-indicator.md" "path": "/docs/api-reference/next.config.js/build-indicator.md"
},
{
"title": "Turbopack-specific options",
"path": "/docs/api-reference/next.config.js/turbopack.md"
} }
] ]
} }
......
...@@ -200,9 +200,8 @@ const nextDev: CliCommand = async (argv) => { ...@@ -200,9 +200,8 @@ const nextDev: CliCommand = async (argv) => {
'configFileName', 'configFileName',
'env', 'env',
'experimental.appDir', 'experimental.appDir',
'experimental.resolveAlias',
'experimental.serverComponentsExternalPackages', 'experimental.serverComponentsExternalPackages',
'experimental.turbopackLoaders', 'experimental.turbo',
'images', 'images',
'pageExtensions', 'pageExtensions',
'onDemandEntries', 'onDemandEntries',
......
...@@ -441,8 +441,17 @@ const configSchema = { ...@@ -441,8 +441,17 @@ const configSchema = {
webpackBuildWorker: { webpackBuildWorker: {
type: 'boolean', type: 'boolean',
}, },
turbopackLoaders: { turbo: {
type: 'object', type: 'object',
additionalProperties: false,
properties: {
loaders: {
type: 'object',
},
resolveAlias: {
type: 'object',
},
},
}, },
turbotrace: { turbotrace: {
type: 'object', type: 'object',
......
...@@ -46,6 +46,40 @@ export interface TypeScriptConfig { ...@@ -46,6 +46,40 @@ export interface TypeScriptConfig {
tsconfigPath?: string tsconfigPath?: string
} }
type JSONValue =
| string
| number
| boolean
| JSONValue[]
| { [k: string]: JSONValue }
type TurboLoaderItem =
| string
| {
loader: string
// At the moment, Turbopack options must be JSON-serializable, so restrict values.
options: Record<string, JSONValue>
}
interface ExperimentalTurboOptions {
/**
* (`next --turbo` only) A mapping of aliased imports to modules to load in their place.
*
* @see [Resolve Alias](https://nextjs.org/docs/api-reference/next.config.js/resolve-alias)
*/
resolveAlias?: Record<
string,
string | string[] | Record<string, string | string[]>
>
/**
* (`next --turbo` only) A list of webpack loaders to apply when running with Turbopack.
*
* @see [Turbopack Loaders](https://nextjs.org/docs/api-reference/next.config.js/turbopack-loaders)
*/
loaders?: Record<string, TurboLoaderItem[]>
}
export interface WebpackConfigContext { export interface WebpackConfigContext {
/** Next.js root directory */ /** Next.js root directory */
dir: string dir: string
...@@ -157,9 +191,7 @@ export interface ExperimentalConfig { ...@@ -157,9 +191,7 @@ export interface ExperimentalConfig {
webVitalsAttribution?: Array<typeof WEB_VITALS[number]> webVitalsAttribution?: Array<typeof WEB_VITALS[number]>
// webpack loaders to use when running turbopack turbo?: ExperimentalTurboOptions
turbopackLoaders?: Record<string, string | string[]>
turbotrace?: { turbotrace?: {
logLevel?: logLevel?:
| 'bug' | 'bug'
...@@ -625,6 +657,7 @@ export const defaultConfig: NextConfig = { ...@@ -625,6 +657,7 @@ export const defaultConfig: NextConfig = {
enableUndici: false, enableUndici: false,
adjustFontFallbacks: false, adjustFontFallbacks: false,
adjustFontFallbacksWithSizeAdjust: false, adjustFontFallbacksWithSizeAdjust: false,
turbo: undefined,
turbotrace: undefined, turbotrace: undefined,
}, },
} }
......
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