1 files changed, 112 insertions, 0 deletions
diff --git a/docs/pages/pack/docs/features/customizing-turbopack.mdx b/docs/pages/pack/docs/features/customizing-turbopack.mdx
new file mode 100644
index 0000000..2ddd6a1
--- /dev/null
+++ b/docs/pages/pack/docs/features/customizing-turbopack.mdx
@@ -0,0 +1,112 @@
+---
+title: Customizing Turbopack
+description: Learn about how to customize Turbopack to your needs
+---
+
+import Callout from "../../../../components/Callout";
+
+# Customizing Turbopack
+
+Turbopack can be customized to transform different files and change how modules are resolved. It supports a subset of webpack's loader API and offers similar configuration aliasing module resolution.
+
+## webpack loaders for Next.js
+
+<Callout type="info">
+  Turbopack for Next.js does not require loaders nor loader configuration for built-in functionality, just as they aren't required for Next.js. Turbopack has built-in support for css and compiling modern JavaScript, so there's no need for `css-loader`, `postcss-loader`, or `babel-loader` if you're just using `@babel/preset-env`.
+</Callout>
+
+If you need loader support beyond what's built in, many webpack loaders already work with Turbopack. There are currently some limitations:
+
+- Only a core subset of the webpack loader API is implemented. This is enough for some popular loaders, and we'll expand our support for this API in the future.
+- Only loaders that return JavaScript code are supported. Loaders that transform files like stylesheets or images are not currently supported.
+- Options passed to webpack loaders must be plain JavaScript primitives, objects, and arrays. For example, it's not possible to pass `require()`d plugin modules as option values.
+
+As of Next 13.2, configuring webpack loaders is possible for Next.js apps through an experimental option in `next.config.js`. `turbo.loaders` can be set as a mapping of file extensions to a list of package names or `{loader, options}` pairs:
+
+```js filename="next.config.js"
+module.exports = {
+  experimental: {
+    turbo: {
+      loaders: {
+        // Option format
+        '.md': [
+          {
+            loader: '@mdx-js/loader',
+            options: {
+              format: 'md',
+            },
+          },
+        ],
+        // Option-less format
+        '.mdx': ['@mdx-js/loader'],
+      },
+    },
+  },
+}
+```
+
+If you need to pass something like the result of importing an external package as a loader option, it's possible to wrap the webpack loader with your own, specifying options there. **This is an interim solution and should not be necessary in the future.** This loader wraps `@mdx-js/loader` and configures the `rehypePrism` rehype plugin:
+
+```js filename="my-mdx-loader.js"
+const mdxLoader = require('@mdx-js/loader');
+const rehypePrism = require('@mapbox/rehype-prism');
+
+module.exports = function (code) {
+	const prevGetOptions = this.getOptions.bind(this);
+	this.getOptions = function getOptions(...args) {
+		return {
+			...prevGetOptions(...args),
+			rehypePlugins: [rehypePrism]
+		}
+	}
+
+	mdxLoader.call(this, code);
+}
+```
+
+Then, configure Next.js to load the wrapper loader:
+
+```js filename="next.config.js"
+module.exports = {
+  experimental: {
+    turbo: {
+      loaders: {
+        '.mdx': ['./my-mdx-loader'],
+      },
+    },
+  },
+}
+```
+
+### Supported loaders
+
+The following loaders have been tested to work with Turbopack's webpack loader implementation:
+
+- [`babel-loader`](https://www.npmjs.com/package/babel-loader)
+- [`@mdx-js/loader`](https://www.npmjs.com/package/@mdx-js/loader)
+- [`@svgr/webpack`](https://www.npmjs.com/package/@svgr/webpack)
+- [`svg-inline-loader`](https://www.npmjs.com/package/svg-inline-loader)
+- [`yaml-loader`](https://www.npmjs.com/package/yaml-loader)
+- [`string-replace-loader`](https://www.npmjs.com/package/string-replace-loader)
+- [`raw-loader`](https://www.npmjs.com/package/raw-loader)
+
+## Resolve aliases
+
+Turbopack can be configured to modify module resolution through aliases, similar to webpack's [`resolve.alias`](https://webpack.js.org/configuration/resolve/#resolvealias) configuration:
+
+```js filename="next.config.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.