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.

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 <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).

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"
             }
           ]
         }

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',

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',

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<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 {
   /** Next.js root directory */
   dir: string
@@ -157,9 +191,7 @@ export interface ExperimentalConfig {
 
   webVitalsAttribution?: Array<typeof WEB_VITALS[number]>
 
-  // webpack loaders to use when running turbopack
-  turbopackLoaders?: Record<string, string | string[]>
-
+  turbo?: ExperimentalTurboOptions
   turbotrace?: {
     logLevel?:
       | 'bug'
@@ -625,6 +657,7 @@ export const defaultConfig: NextConfig = {
     enableUndici: false,
     adjustFontFallbacks: false,
     adjustFontFallbacksWithSizeAdjust: false,
+    turbo: undefined,
     turbotrace: undefined,
   },
 }