Migrating from Nx
This guide will help you migrate an existing Nx repository to Turborepo.
- Explore key concepts by migrating from the Nx starter to Turborepo
- Considerations for more complex migration scenarios
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.
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.
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
.
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.
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.
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.
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.
Step 6: Run you package manager's install command
Update your lockfile by running your installation command.
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.
You can also optionally install turbo
globally for added convenience when working with Turborepo.
Step 8: Add a turbo.json
Create a turbo.json
at the root to register your tasks and describe their task dependencies.
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:
Step 10: Enable Remote Caching (optional)
By default, Turborepo will connect to the free-to-use Vercel Remote Cache when you run:
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
toturbo run lint
- Migrating one package/project at a time: Changing
nx run-many lint test --projects=web
toturbo run lint test --filter=web
- Double-running some of your tasks: To ensure stability, you may choose to run
turbo run lint
andnx 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.
- Ensure the package’s directory is included in the workspace definition (like
./packages/*
). - Add a
package.json
to the package with the scripts it needs to run. - 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
Nx | Turborepo |
---|---|
sharedGlobals | globalDependencies |
sharedGlobals.env | globalEnv |
sharedGlobals.namedInput | globalDependencies |
cacheDirectory | cacheDir |
Task configuration
Nx | Turborepo |
---|---|
inputs files | tasks[task].inputs |
inputs.env | tasks[task].env |
outputs files | tasks[task].outputs |
cache | tasks[task].cache |
CLI equivalents
Nx | Turborepo |
---|---|
nx generate | turbo generate |
nx run | turbo run |
nx run-many | turbo run |
nx reset | --force |
--parallel | --concurrency |
--nxBail | --continue |
--projects | --filter |
--graph | --graph |
--output-style | --log-order |
--no-cloud | --cache |
--verbose | --verbosity |
Was this helpful?