Skip to content

Commit

Permalink
docs: make incremental migration more prominent on Nx doc (#9796)
Browse files Browse the repository at this point in the history
### Description

I received good feedback that I buried the recommendation for
incremental migration too much. This PR surfaces that information more
readily.

### Testing Instructions

👀
  • Loading branch information
anthonyshew authored Jan 24, 2025
1 parent f7a67d2 commit 02fc06c
Showing 1 changed file with 11 additions and 4 deletions.
15 changes: 11 additions & 4 deletions docs/repo-docs/guides/migrating-from-nx.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ import { PackageManagerTabs, Tabs, Tab } from '#/components/tabs';

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

- Explore key concepts by [migrating from the Nx starter to Turborepo](#migration-steps)
- Considerations for [more complex migration scenarios](#advanced-migration-considerations)

## Why switch?

There are several reasons why you might want to switch from from Nx to Turborepo.
Expand Down Expand Up @@ -420,6 +423,14 @@ You may also configure a self-hosted Remote Cache, which does not require a lice

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](/repo/docs/crafting-your-repository/managing-dependencies#best-practices-for-dependency-installation) 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.
Expand All @@ -438,10 +449,6 @@ You’ll follow roughly the same set of steps as above to add a package to your

Turborepo natively supports JavaScript and TypeScript, with secondary support for any other languages you’d like to use. [Visit the Multi-Language support documentation](/repo/docs/guides/multi-language) to learn more.

### Migrate complex monorepos incrementally

In particularly complex monorepos, we recommend breaking up the migration into parts to de-risk the migration. You’ll use both Nx and Turborepo in your codebase for a portion of time as you grow more comfortable with Turborepo, dropping your dependency on Nx gradually.

## Configuration equivalents

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

0 comments on commit 02fc06c

Please sign in to comment.