Upgrading to Next.js version 13 with Turbopack

Next.js, a React framework, released version 13 in October 2022. We were maintaining a web application built with Next.js version 12, so we went ahead and upgraded. During the upgrade, we encountered several issues which we would like to share here.

We first started with the next.config.jsconfiguration file. This file is created for the custom advanced configuration of Next.js. It is located in the root of your project directory (next to package.json).

In Next.js 12, our next.config.js file looks like this:

// next.config.js

const { withSentryConfig } = require('@sentry/nextjs');

const moduleExports = {
  images: {
    domains: [
      "res.cloudinary.com",
      ....
    ],
  },
  env: {
    postsPerPage: 6,
  },
  swcMinify: true,
};

const sentryWebpackPluginOptions = {
  silent: true, // Suppresses all logs
};

module.exports = withSentryConfig(moduleExports, sentryWebpackPluginOptions);

In version 13, Next.js' SWC compiler is used for minification by default. It is claimed to be 7x faster than Terser (used by default in 12). So we no longer had to state swcMinify: true in next.config.js in order to use SWC. But if Terser is still needed for any reason, it can be configured as below:

swcMinify: false,

Next, we tried out Turbopack, which is a new JavaScript bundler and the successor to Webpack. It is in alpha release and can be enabled in development mode. It is claimed that on large applications, Turbopack updates 10x faster than Vite and 700x faster than Webpack. To enable Turbopack, we started with the following change:

// package.json

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

After starting up our development server, we encountered the below error:

$ next dev --turbo
info  - Loaded env from /var/app/.env
>>> TURBOPACK (alpha)
.....
Warning: You are using configuration that may require additional
setup with Turbopack. If you already made these changes please
ignore this warning.

- PostCSS detected (postcss.config.js)
  PostCSS is not yet supported by Next.js v13 with Turbopack.
  To use with Turbopack, see: https://nextjs.link/turbopack-postcss

- Tailwind detected (tailwind.config.js)
  Tailwind is not yet supported by Next.js v13 with Turbopack.
  To use with Turbopack, see: https://nextjs.link/turbopack-tailwind

Error: You are using configuration and/or tools that are not yet
supported by Next.js v13 with Turbopack:

Turbopack doesn't currently support Tailwind CSS out of the box. But we had previously configured our application to use Tailwind CSS and PostCSS as below:

// package.json

  "devDependencies": {
    ....
    "autoprefixer": "^10.4.13",
    "postcss": "^8.4.19",
    "tailwindcss": "^3.2.4"
  }

// postcss.config.js

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

// tailwind.config.js

module.exports = {
  content: ['./pages/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}'],
  theme: { .... },
  plugins: [ .... ],
}

// styles/globals.css

@tailwind base;
@tailwind components;
@tailwind utilities;

// pages/_app.js

import '../styles/globals.css';

However, we found a workaround that allows Turbopack to work with Tailwind CSS.

We use yarn package manager to install the npm package called concurrently:

yarn add --dev concurrently

This adds concurrently as part of devDependenciesinpackage.json:

// package.json

  "devDependencies": {
    ....
    "concurrently": "^7.6.0",
  }

Then we moved the dev and build commands to scripts, and imported the compiled CSS output file.

// package.json

    "scripts": {
      "dev": "concurrently \"next dev --turbo\" \"tailwindcss --input ./styles/globals.css --output ./styles/output.css --watch\"",
      "build": "tailwindcss ./styles/globals.css --output ./styles/output.css && next build",
    }

// pages/_app.js

import '../styles/output.css';

concurrently allows us to run Tailwind CLI in parallel to compile our CSS styles/globals.css into an output file styles/output.css. We then import this output file in javascript code.

Starting up the development server again, we see that the Tailwind CSS issue is now solved.

But we ran into another issue:

- Waiting for framework port 3000. This can be configured using the 'targetPort' property in the netlify.toml
$ concurrently "next dev --turbo" "tailwindcss --input ./styles/globals.css --output ./styles/output.css --watch"
    info  - Loaded env from /var/app/.env
    >>> TURBOPACK (alpha)

    Thank you for trying Next.js v13 with Turbopack! As a reminder,
    Turbopack is currently in alpha and not yet ready for production.
    We appreciate your ongoing support as we work to make it ready
    for everyone.

    Error: You are using configuration and/or tools that are not yet
    supported by Next.js v13 with Turbopack:

    - Unsupported Next.js configuration option(s) (next.config.js)
      The only configurations options supported are:
        - experimental.serverComponentsExternalPackages
        - experimental.transpilePackages
      To use Turbopack, remove other configuration options.
....

For next.config.js, not all the Webpack supported configurations are currently supported by Turbopack. Here are a few of them:

1. env
   ‍This Next.js feature is using a Webpack plugin called DefinePlugin behind the scenes. More information can be found here:- next.config.js: Environment Variables | Next.js- DefinePlugin | webpack

2. images -> domainsfor next/image
   The domains is used to specify the allowed hostnames for external images.

3. Sentry-related withSentryConfig and sentryWebpackPluginOptions
   Sentry is an error-tracking tool which allows integration with Next.js. But it hasn't supported building with Turbopack at the moment. More information can be found here:- Next.js | Sentry Documentation

In conclusion, we were able to migrate to Next.js version 13. But we couldn't enable Turbopack due to certain features not being supported yet.