From d726fe30b7ba0ed1b59ec07eeda94ecdde3cb6bc Mon Sep 17 00:00:00 2001 From: Will Binns-Smith Date: Wed, 8 Feb 2023 15:10:26 -0800 Subject: [PATCH] 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. --- .../api-reference/next.config.js/turbopack.md | 70 +++++++++++++++++++ docs/manifest.json | 4 ++ packages/next/src/cli/next-dev.ts | 3 +- packages/next/src/server/config-schema.ts | 11 ++- packages/next/src/server/config-shared.ts | 39 ++++++++++- 5 files changed, 121 insertions(+), 6 deletions(-) create mode 100644 docs/api-reference/next.config.js/turbopack.md diff --git a/docs/api-reference/next.config.js/turbopack.md b/docs/api-reference/next.config.js/turbopack.md new file mode 100644 index 0000000000000..dad882dcea556 --- /dev/null +++ b/docs/api-reference/next.config.js/turbopack.md @@ -0,0 +1,70 @@ +--- +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 +} +``` + +## 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). diff --git a/docs/manifest.json b/docs/manifest.json index 76405ea62a0eb..581c53ced2236 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -571,6 +571,10 @@ { "title": "Build indicator", "path": "/docs/api-reference/next.config.js/build-indicator.md" + }, + { + "title": "Turbopack-specific options", + "path": "/docs/api-reference/next.config.js/turbopack.md" } ] } diff --git a/packages/next/src/cli/next-dev.ts b/packages/next/src/cli/next-dev.ts index a4fec4e9c18ff..9400acad3734f 100644 --- a/packages/next/src/cli/next-dev.ts +++ b/packages/next/src/cli/next-dev.ts @@ -200,9 +200,8 @@ const nextDev: CliCommand = async (argv) => { 'configFileName', 'env', 'experimental.appDir', - 'experimental.resolveAlias', 'experimental.serverComponentsExternalPackages', - 'experimental.turbopackLoaders', + 'experimental.turbo', 'images', 'pageExtensions', 'onDemandEntries', diff --git a/packages/next/src/server/config-schema.ts b/packages/next/src/server/config-schema.ts index 4a5125befb096..5c9ea4278b922 100644 --- a/packages/next/src/server/config-schema.ts +++ b/packages/next/src/server/config-schema.ts @@ -441,8 +441,17 @@ const configSchema = { webpackBuildWorker: { type: 'boolean', }, - turbopackLoaders: { + turbo: { type: 'object', + additionalProperties: false, + properties: { + loaders: { + type: 'object', + }, + resolveAlias: { + type: 'object', + }, + }, }, turbotrace: { type: 'object', diff --git a/packages/next/src/server/config-shared.ts b/packages/next/src/server/config-shared.ts index 1f2b867981c3f..442165d030eff 100644 --- a/packages/next/src/server/config-shared.ts +++ b/packages/next/src/server/config-shared.ts @@ -46,6 +46,40 @@ export interface TypeScriptConfig { 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 + } + +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 + > + + /** + * (`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 +} + export interface WebpackConfigContext { /** Next.js root directory */ dir: string @@ -157,9 +191,7 @@ export interface ExperimentalConfig { webVitalsAttribution?: Array - // webpack loaders to use when running turbopack - turbopackLoaders?: Record - + turbo?: ExperimentalTurboOptions turbotrace?: { logLevel?: | 'bug' @@ -625,6 +657,7 @@ export const defaultConfig: NextConfig = { enableUndici: false, adjustFontFallbacks: false, adjustFontFallbacksWithSizeAdjust: false, + turbo: undefined, turbotrace: undefined, }, }