From a80a8ced84ff08b90a00c9eda4024c4e966b2f07 Mon Sep 17 00:00:00 2001 From: Anthony Shew Date: Fri, 24 Jan 2025 12:11:12 -0700 Subject: [PATCH] docs: make incremental migration more prominent on Nx doc --- docs/repo-docs/guides/migrating-from-nx.mdx | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/repo-docs/guides/migrating-from-nx.mdx b/docs/repo-docs/guides/migrating-from-nx.mdx index 93ea205cf476f..777e0fb78df9a 100644 --- a/docs/repo-docs/guides/migrating-from-nx.mdx +++ b/docs/repo-docs/guides/migrating-from-nx.mdx @@ -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. @@ -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. @@ -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.