Guide to nextjs + turbopack ⚡️🏎️

I really like Next.js, but it's commonly known to become really slow when your project grows.
On my side, I could wait sometimes 40 seconds 🤯 to have one page compiled and displayed when developing smartrole.ai, a big monorepo with turborepo, nextjs, pnpm, tailwind and prisma amongst others.
I've tried to play with NextJS settings, like webpack, serverExternalPackages, or modularizeImports, but nothing really works.

TBH, I was even considering switching to another framework.😢 Then comes Rust in the game, with Turbopack...
Enabling Turbopack is not straightforward at all, but it’s worth it: now it's just a matter of 1 or 2 seconds to compile ! 🤩

So here's a guide on how I achieved this leap in performance and tackled some common issues along the way.

Installation

The easy part. In package.json, simply add --turbo:

"scripts": {
  "dev": "next dev --turbo"
}

Note: you also have --turbopack options, which does the same, except you can't configure it using the experimental.turbo option.

Remove the webpacksection from your next.config.ts, as Turbopack comes as a replacement of webpack.

Troubleshooting Common Issues

Package resolves to a different version

When working with Turbopack, you might encounter an error like this:

The request prettier/standalone matches serverExternalPackages (or the default list).
The package resolves to a different version when requested from the project directory (3.5.1) compared to the package requested from the importing module (3.4.2).
Make sure to install the same version of the package in both locations.

Solution: To resolve version mismatches, add pnpm.overrides to package.json:

"pnpm": {
    "overrides": {
      "prettier": "3.5.2"
    }
  },

Package can't be external

If you encounter an error stating that a package cannot be external, you might see something like this:

Package @libsql/client (serverExternalPackages or default list) can't be external
The request @libsql/client matches serverExternalPackages (or the default list), but it can't be external:
The request could not be resolved by Node.js from the project directory.
Packages that should be external need to be installed in the project directory, so they can be resolved from the output files.
Try to install the package into the project directory.
Next.js package not found

Solution: Create a .npmrc file at the root of your monorepo with the following content to ensure all dependencies are installed correctly:

legacy-peer-deps=true
public-hoist-pattern[]=*import-in-the-middle*
public-hoist-pattern[]=*require-in-the-middle*
public-hoist-pattern[]=*motion/react*
public-hoist-pattern[]=*motion*
public-hoist-pattern[]=*keyv*
public-hoist-pattern[]=*chart.js*
public-hoist-pattern[]=*@prisma/client*
public-hoist-pattern[]=*@aws-sdk/client-s3*

For further context, refer to the GitHub issue related to this problem.

Next.js package not found

Sometimes, Turbopack may fail to locate the Next.js package, resulting in an error like:

- Execution of get_entrypoints_with_issues failed
- Execution of Project::entrypoints failed
- Execution of AppProject::routes failed
- Execution of directory_tree_to_entrypoints_internal failed
- Execution of directory_tree_to_entrypoints_internal failed
- Execution of directory_tree_to_loader_tree failed
- Execution of *FileSystemPath::join failed
- Execution of get_next_package failed
- Next.js package not found]

Solution: To fix this, delete the pnpm-lock.yaml file. This can help resolve dependency resolution issues.

See the GitHub discussion for more details.

The "path" argument must be of type string. Received undefined

It appears with next 15.2.0

Solution: Downgrade to a more stable version by setting your Next.js version in package.json to 15.1.7.

Refer to this GitHub issue for more insights.