Turborepo

Migrating from Nx

This guide will help you migrate an existing Nx repository to Turborepo.

Why switch?

There are several reasons why you might want to switch from from Nx to Turborepo.

Ecosystem standards

Turborepo is built on top of package manager workspaces, meaning more tools and workflows are likely to work without plugins or other workarounds. By comparison, the default Nx starter uses conventions and strategies unique to Nx, and you can expect to write more Nx-only code as your codebase grows.

More control of source code

Nx’s philosophy involves wrapping your code with layers of plugins, other dependencies, and Nx-specific code. Instead, Turborepo infers your repository’s needs from its structure and source code. Since your source code goes through fewer layers of abstraction to be analyzed, you maintain greater control of your repository.

Less configuration

Migrating to Turborepo will likely require deleting previous configuration needed for Nx. Turborepo will automatically infer much of what your repository needs. For example, here are the tool-specific configurations you'll find in the default starters for Turborepo and Nx.

turbo.json
{
  "$schema": "/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "lint": {
      "dependsOn": ["^lint"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Free Remote Caching

Turborepo’s Remote Caching stores the results of your task on a cloud server. This saves enormous amounts of time by preventing duplicated work across your entire organization. Vercel Remote Cache has saved teams over 500 years of compute so far.

Since Nx 19.7, similar functionality is a paid-for feature, even when self-hosting. Remote Caching with Turborepo is free when self-hosting or using Vercel Remote Cache.

Migration steps

Our goal for this migration is to get a working Turborepo task as quickly as possible, so that you can adopt Turborepo features incrementally. We’ll start by using the Nx scaffolder to create a repository with a Next.js app.

Terminal
npx create-nx-workspace --preset=next --ci=skip --e2eTestRunner=none --style=tailwind --nextAppDir=true --nextSrcDir=false --packageManager=pnpm --appName=starter

Step 1: Update .gitignore

Turborepo uses the .turbo directory to hold local caches and other information about your repository. For this reason, it should be added to your .gitignore.

.gitignore
.turbo

Step 2: Add a workspace definition

Turborepo is built on top of package manager workspaces, a JavaScript ecosystem standard. Add the directory paths to the workspace that will contain packages.

package.json
{
  "workspaces": ["apps/*"]
}

Step 3: Add a package.json to the application

Rather than adding additional configuration files like project.json, Turborepo uses the standard package.json file.

Add a package.json to the starter application. Create a package.json at ./apps/starter/package.json that contains a dev and build script.

./apps/starter/package.json
{
  "name": "starter",
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}

Step 4: Remove Nx plugin

Remove the Nx plugin from ./apps/starter/next.config.js. The example file below doesn’t have configuration, though your existing Next.js application may need some.

./apps/starter/next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {};
 
module.exports = nextConfig;

Step 5: Add the packageManager field

The root package.json needs to have the packageManager field. This ensures developers in the repository use the correct package manager, and that Turborepo can optimize your package graph based on your lockfile.

./package.json
{
  "packageManager": "npm@10.0.0"
}

Step 6: Run you package manager's install command

Update your lockfile by running your installation command.

Terminal
npm install

Once you've done this, you should see a lockfile diff, indicating that the package has been added to the package manager's workspace.

Step 7: Install Turborepo

Add Turborepo to the root package.json of the workspace.

Terminal
npm install turbo --save-dev

You can also optionally install turbo globally for added convenience when working with Turborepo.

Terminal
npm install turbo --global

Step 8: Add a turbo.json

Create a turbo.json at the root to register your tasks and describe their task dependencies.

./turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Step 9: Run turbo build

Build the application with Turborepo. Using global turbo, this would be turbo build. You can also run the command through your package manager:

Terminal
npx turbo run build

Step 10: Enable Remote Caching (optional)

By default, Turborepo will connect to the free-to-use Vercel Remote Cache when you run:

Terminal
turbo login
turbo link

You may also configure a self-hosted Remote Cache, which does not require a license or any other fees.

Advanced migration considerations

While the migration guide above is a good starting point, the breadth of possibilities and capabilities of monorepos means that its difficult to create generalized instructions for all cases. Below, we’ve listed some common next steps that you may be thinking about.

Migrate complex monorepos incrementally

We encourage incremental migration, meaning you will have both of Nx and Turborepo in your repository at the same time. Make sure to spend time understanding how your Nx task graph is constructed. Splitting up the task graph may include strategies like:

  • Migrating one task at a time: Changing nx run lint to turbo run lint
  • Migrating one package/project at a time: Changing nx run-many lint test --projects=web to turbo run lint test --filter=web
  • Double-running some of your tasks: To ensure stability, you may choose to run turbo run lint and nx run lint while you're still getting comfortable and builiding certainty in the early phases of your migration.

Installing dependencies where they're used

Turborepo recommends installing packages where they're used to improve cache hit ratios, help dependency pruning capability, and clarify for developers which dependencies are meant for which packages. This is different from the Nx strategy, where all dependencies are installed at the root of the repository, making all dependencies available to all packages in the workspace.

Once you have tasks running through Turborepo, we highly recommend that you move dependencies to the package.json's for packages and applications that need them. Visit our documentation on managing dependencies to learn more.

Creating shared packages

You’ll follow roughly the same set of steps as above to add a package to your package manager’s workspace.

  1. Ensure the package’s directory is included in the workspace definition (like ./packages/* ).
  2. Add a package.json to the package with the scripts it needs to run.
  3. Check task dependencies in turbo.json to make sure your dependency graph meets your requirements.

Multi-language monorepos

Turborepo natively supports JavaScript and TypeScript, with secondary support for any other languages you’d like to use. Visit the Multi-Language support documentation to learn more.

Configuration equivalents

Configuration found in nx.json can be mapped to turbo.json using the tables below.

The majorify of globs for capturing files are the same between Nx and Turborepo. See our file glob specification for details and edge cases.

Global configuration

NxTurborepo
sharedGlobalsglobalDependencies
sharedGlobals.envglobalEnv
sharedGlobals.namedInputglobalDependencies
cacheDirectorycacheDir

Task configuration

NxTurborepo
inputs filestasks[task].inputs
inputs.envtasks[task].env
outputs filestasks[task].outputs
cachetasks[task].cache

CLI equivalents

NxTurborepo
nx generateturbo generate
nx runturbo run
nx run-manyturbo run
nx reset--force
--parallel--concurrency
--nxBail--continue
--projects--filter
--graph--graph
--output-style--log-order
--no-cloud--cache
--verbose--verbosity