Turbopack experimental fields docs and schema

docs/api-reference/next.config.js/turbopack-loaders.md

@@ -0,0 +1,41 @@
+---
+description: Configure Next.js with Turbopack to load webpack loaders
+---
+
+# Turbopack Loaders
+
+Currently, Turbopack supports a subset of webpack's loader API, allowing you to use some webpack loaders to transform code in Turbopack.
+
+> **Warning**: This feature is experimental and will only work with `next --turbo`.
+
+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: {
+    turbopackLoaders: {
+      '.md': [
+        {
+          loader: '@mdx-js/loader',
+          options: {
+            format: 'md',
+          },
+        },
+      ],
+      '.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 />
+}
+```
+
+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).

docs/api-reference/next.config.js/turbopack-resolve-alias.md

@@ -0,0 +1,28 @@
+---
+description: Configure Next.js with Turbopack to alias module resolution
+---
+
+# Turbopack 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.
+
+> **Warning**: This feature is experimental and will only work with `next --turbo`.
+
+To configure resolve aliases, map imported patterns to their new destination in `next.config.js`:
+
+```js
+module.exports = {
+  experimental: {
+    turbopackResolveAlias: {
+      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).

docs/manifest.json

@@ -571,6 +571,14 @@
             {
               "title": "Build indicator",
               "path": "/docs/api-reference/next.config.js/build-indicator.md"
+            },
+            {
+              "title": "Turbopack Loaders",
+              "path": "/docs/api-reference/next.config.js/turbopack-loaders.md"
+            },
+            {
+              "title": "Resolve Alias",
+              "path": "/docs/api-reference/next.config.js/turbopack-resolve-alias.md"
             }
           ]
         }

packages/next/src/server/config-schema.ts

@@ -441,6 +441,9 @@ const configSchema = {
         webpackBuildWorker: {
           type: 'boolean',
         },
+        resolveAlias: {
+          type: 'object',
+        },
         turbopackLoaders: {
           type: 'object',
         },

packages/next/src/server/config-shared.ts

@@ -46,6 +46,21 @@ export interface TypeScriptConfig {
   tsconfigPath?: string
 }
 
+type JSONValue =
+  | string
+  | number
+  | boolean
+  | JSONValue[]
+  | { [k: string]: JSONValue }
+
+type TurbopackLoaderItem =
+  | string
+  | {
+      loader: string
+      // At the moment, Turbopack options must be JSON-serializable, so restrict values.
+      options: Record<string, JSONValue>
+    }
+
 export interface WebpackConfigContext {
   /** Next.js root directory */
   dir: string
@@ -157,8 +172,22 @@ export interface ExperimentalConfig {
 
   webVitalsAttribution?: Array<typeof WEB_VITALS[number]>
 
-  // webpack loaders to use when running turbopack
-  turbopackLoaders?: Record<string, string | string[]>
+  /**
+   * (`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)
+   */
+  turbopackLoaders?: Record<string, TurbopackLoaderItem | TurbopackLoaderItem[]>
 
   turbotrace?: {
     logLevel?: