Pack
Docs
Migrating from Webpack

Migrating from webpack to Turbopack

Turbopack now implements basic webpack loader support and configuration familiar to webpack users

We're planning Turbopack as the successor to webpack. In the future, we plan to give Turbopack all the tools needed to support your webpack app.

Currently, Turbopack supports a subset of webpack's loader API and offers similar configuration aliasing module resolution. Note that using webpack-based Next.js plugins as-is from next.config.js is not yet possible.

webpack loaders for Next.js

Firstly, Turbopack for Next.js does not require loaders nor loader configuration for built-in functionality, just as they aren't required for Next.js. There's no need for css-loader, postcss-loader, or babel-loader if you're just using @babel/preset-env.

If you need loader support beyond what's built in, some webpack loaders, including @mdx-js/loader (opens in a new tab) already work with Turbopack! There are currently some limitations:

  • At the moment, 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.
  • 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.

At the moment, configuring webpack loaders is possible for Next.js apps through an experimental option in next.config.js. turbopack.loaders can be set to a mapping of file extensions to a list of package names or {loader, options} pairs:

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

Resolve aliases

Turbopack can be configured to modify module resolution through aliases, similar to webpack's resolve.alias (opens in a new tab) configuration:

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 (opens in a new tab). 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.

FAQ

Which loaders are currently supported?

The following loaders have been tested to work with Turbopack's webpack loader implementation:

Will it be compatible with webpack's API?

webpack has a huge API. It's extremely flexible and extensible, which is a big reason why it's so popular.

We're planning on making Turbopack very flexible and extensible, but we're not planning 1:1 compatibility with webpack. This lets us make choices which improve on webpack's API, and lets us optimize for speed and efficiency.

Will we be able to use webpack plugins?

webpack plugins are a crucial part of webpack's ecosystem. They let you customize your toolchain, giving you low-level tools to maximize your productivity.

Unlike loaders, webpack plugins can be tightly integrated with webpack's internals.

Since we're not offering 1:1 API compatibility for plugins, most won't work out of the box with Turbopack. However, we're working on porting several of the most popular webpack plugins to Turbopack.

Last updated on 2023-02-09T00:25:43.000Z