next-turbopack

Imported from pohlai88/AFENDA (.agents/skills/next-turbopack/SKILL.md). Install upstream with npx skills add pohlai88/AFENDA --skill next-turbopack. Copyright stays with the author.

The turbopack option lets you customize Turbopack to transform different files and change how modules are resolved.

Good to know: The turbopack option was previously named experimental.turbo in Next.js versions 13.0.0 to 15.2.x. The experimental.turbo option will be removed in Next.js 16.

If you are using an older version of Next.js, run npx @next/codemod@latest next-experimental-turbo-to-turbopack . to automatically migrate your configuration.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    // ...
  },
}

export default nextConfig

/** @type {import('next').NextConfig} */
const nextConfig = {
  turbopack: {
    // ...
  },
}

module.exports = nextConfig

Good to know:

• Turbopack for Next.js does not require loaders or loader configuration for built-in functionality. 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 using @babel/preset-env.

Reference

Options

The following options are available for the turbopack configuration:

Supported loaders

The following loaders have been tested to work with Turbopack's webpack loader implementation, but many other webpack loaders should work as well even if not listed here:

• babel-loader (Configured automatically if a Babel configuration file is found)
• @svgr/webpack
• svg-inline-loader
• yaml-loader
• string-replace-loader
• raw-loader
• sass-loader (Configured automatically)
• graphql-tag/loader

Missing Webpack loader features

Turbopack uses the loader-runner library to execute webpack loaders, which provides most of the standard loader API. However, some features are not supported:

Module loading:

• importModule - No support
• loadModule - No support

File system and output:

• fs - Partial support: only fs.readFile is currently implemented.
• emitFile - No support

Context properties:

• version - No support
• mode - No support
• target - No support

Utilities:

• utils - No support
• resolve - No support (use getResolve instead)

If you have a loader that is critically dependent upon one of these features please file an issue.

Examples

Root directory

Turbopack uses the root directory to resolve modules. Files outside of the project root are not resolved.

The reason files are not resolved outside of the project root is to improve cache validation, reduce filesystem watching overhead, and reduce the number of resolving steps needed.

Next.js automatically detects the root directory of your project. It does so by looking for one of these files:

• pnpm-lock.yaml
• package-lock.json
• yarn.lock
• bun.lock
• bun.lockb

If you have a different project structure, for example if you don't use workspaces, you can manually set the root option:

const path = require('path')
module.exports = {
  turbopack: {
    root: path.join(__dirname, '..'),
  },
}

To resolve files from linked dependencies outside the project root (via npm link, yarn link, pnpm link, etc.), you must configure the turbopack.root to the parent directory of both the project and the linked dependencies.

While this expands the scope of filesystem watching, it's typically only necessary during development when actively working on linked packages.

Configuring webpack loaders

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. Currently, there is enough coverage for some popular loaders, and we'll expand our API support 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() plugin modules as option values.

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. Rules are evaluated in order.

Here is an example below using the @svgr/webpack loader, which enables importing .svg files and rendering them as React components.

module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

Good to know: Globs used in the rules object match based on file name, unless the glob contains a / character, which will cause it to match based on the full project-relative file path. Windows file paths are normalized to use unix-style / path separators.

Turbopack uses a modified version of the Rust globset library.

For loaders that require configuration options, you can use an object format instead of a string:

module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: [
          {
            loader: '@svgr/webpack',
            options: {
              icon: true,
            },
          },
        ],
        as: '*.js',
      },
    },
  },
}

Good to know: Prior to Next.js version 13.4.4, turbopack.rules was named turbo.loaders and only accepted file extensions like .mdx instead of *.mdx.

Advanced webpack loader conditions

You can further restrict where a loader runs using the advanced condition syntax:

module.exports = {
  turbopack: {
    rules: {
      // '*' will match all file paths, but we restrict where our
      // rule runs with a condition.
      '*': {
        condition: {
          all: [
            // 'foreign' is a built-in condition.
            { not: 'foreign' },
            // 'path' can be a RegExp or a glob string. A RegExp matches
            // anywhere in the full project-relative file path.
            { path: /^img\/[0-9]{3}\// },
            {
              any: [
                { path: '*.svg' },
                // 'content' is always a RegExp, and can match
                // anywhere in the file.
                { content: /\<svg\W/ },
              ],
            },
          ],
        },
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

• Supported boolean operators are {all: [...]}, {any: [...]} and {not: ...}.
• Supported customizable operators are {path: string | RegExp} and {content: RegExp}. If path and content are specified in the same object, it acts as an implicit and.

In addition, a number of built-in conditions are supported:

• browser: Matches code that will execute on the client. Server code can be matched using {not: 'browser'}.
• foreign: Matches code in node_modules, as well as some Next.js internals. Usually you'll want to restrict loaders to {not: 'foreign'}. This can improve performance by reducing the number of files the loader is invoked on.
• development: Matches when using next dev.
• production: Matches when using next build.
• node: Matches code that will run on the default Node.js runtime.
• edge-light: Matches code that will run on the Edge runtime.

Rules can be an object or an array of objects. An array is often useful for modeling disjoint conditions:

module.exports = {
  turbopack: {
    rules: {
      '*.svg': [
        {
          condition: 'browser',
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
        {
          condition: { not: 'browser' },
          loaders: [require.resolve('./custom-svg-loader.js')],
          as: '*.js',
        },
      ],
    },
  },
}

Good to know: All matching rules are executed in order.

Resolving aliases

Turbopack can be configured to modify module resolution through aliases, similar to webpack's resolve.alias configuration.

To configure resolve aliases, map imported patterns to their new destination in next.config.js:

module.exports = {
  turbopack: {
    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' 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.

Resolving custom extensions

Turbopack can be configured to resolve modules with custom extensions, similar to webpack's resolve.extensions configuration.

To configure resolve extensions, use the resolveExtensions field in next.config.js:

module.exports = {
  turbopack: {
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.json'],
  },
}

This overwrites the original resolve extensions with the provided list. Make sure to include the default extensions.

For more information and guidance for how to migrate your app to Turbopack from webpack, see Turbopack's documentation on webpack compatibility.

Debug IDs

Turbopack can be configured to generate debug IDs in JavaScript bundles and source maps.

To configure debug IDs, use the debugIds field in next.config.js:

module.exports = {
  turbopack: {
    debugIds: true,
  },
}

The option automatically adds a polyfill for debug IDs to the JavaScript bundle to ensure compatibility. The debug IDs are available in the globalThis._debugIds global variable.

Version History

For a semantic overview of all documentation, see /docs/sitemap.md

For an index of all available documentation, see /docs/llms.txt