fix(docs): Feedback from Nx team on migration doc #10003
Conversation
turbo-orchestrator
bot
added
area: docs
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
@JamesHenry is attempting to deploy a commit to the Vercel Team on Vercel. A member of the Team first needs to authorize it. |
anthonyshew
changed the title
|
|
||
| </Tabs> | ||
|
|
||
| ### Free Remote Caching |
There was a problem hiding this comment.
I've not watched the video in full maybe their an explanation. I love NX and I know nx offer "free license" but I think this section should remain as it's not the same and for Enterprise its a paid license.
Lot of the rest fair just thisnsection removal seems strange
There was a problem hiding this comment.
There is an explanation given in the video, but I'm having the hardest time understanding it.
An explicit reason for this section getting written has been an influx of new users to Turborepo, coming from Nx, because of a change in the cost structure of using Nx. They're finding that features that they used to use for free aren't free anymore.
Note that this is specifically not my experience or something I went out of my way to invent. This is written how it is because of experiences other developers have shared with me. The first couple times I heard it, I went to read the docs about how the pricing is meant to work, and was confused by the explanations and documentation given. In one place it would sound like its part of the open-source offering, and the next would sound like it isn't.
I continually pestered the people I was talking to about this, and insisted that maybe they were misunderstanding the documentation (hoping that their familiarity with the tool or Nx team would lead me to concluding that the feature is still free), but they repeated that it was the case that they were losing features.
From the conversations I've had, questions I've answered, and frequency at which this comes up, I don't see any other option than having to mention this paradigm in this documentation.
There was a problem hiding this comment.
Ive been extremely vocal around this with NX. Many still feel like the free license not enough and their no way to run remote cache without it being a NX licensed software. I've got a hot patch but once it goes to rust it's nesr impossible
|
|
||
| Create a `turbo.json` at the root to register your tasks and describe their task dependencies. | ||
| Create a `turbo.json` at the root to register your tasks and describe their task dependencies. Note, this does not yet cover the same functionality as was in the original `nx.json` and is an example of getting started quickly with a subset of capabilities. |
There was a problem hiding this comment.
Can you say what tasks or configuration are missing?
There was a problem hiding this comment.
Sure yeah, again this is regarding the argument that Nx requires "more configuration" and this felt like it wasn't clearly established as being intentionally not "apples to apples".
Here in Step 7 you have a tasks configuration that only deals with building and serving the Next.js application, whereas the nx.json we start the process with covers building, serving (both from source and from dist), typechecking and linting.
| ### Vercel Interoperability | ||
|
|
||
| ### More control of source code | ||
| If you are already a part of the Vercel ecosystem, for example using the infrastructure provided by us, then you will feel right at home with Turborepo. | ||
|
|
||
| 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. | ||
| We provide dedicated [Remote Caching](/repo/docs/core-concepts/remote-caching) options for all Turborepo users, where we store 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](https://vercel.com/docs/monorepos/remote-caching) has saved teams over 500 years of compute so far. |
There was a problem hiding this comment.
I'm having a hard time seeing how Turborepo working great on Vercel is relevant to this doc. While true, this documentation is meant for folks migrating from Nx to Turborepo. It doesn't have anything to do with Vercel, nor should it. It's very possible that someone could be getting acquainted with Turborepo for the first time on this document, and this section would be misleading for them.
I don't know how else to read these edits other than a projection about the way Nx has been closing off the open-source parts of its offering, according to what Nx users have been repeatedly telling me. I don't write this to be rude or antagonistic, but I can't tell what these edits are meant to be for and am having to guess.
We take great pride in creating an open-source project that anyone can use how they wish. As fate would have it, this morning we just finished up some improvements for self-hosting (ref and ref) and I've been working on creating an OpenAPI spec viewer for our docs the past week or so.
Were you meaning something else/I'm not getting it?
There was a problem hiding this comment.
I'm sorry if it wasn't clear in the video, but in it I tried to relay the following: I am not an expert on Turborepo, and so this was an honest attempt by me to provide additional, objective steelman arguments as to why you might want to switch.
As I demonstrated, some of the existing arguments needed to be removed completely due to their inaccuracy, so I wanted to offer up ideas for replacements that I felt were honest and objective (again with the caveat that I am not deep enough to know all of the potential benefits of Turborepo and they are therefore high level starting points for discussion).
If you disagree with this point and don't want it included that's totally fine, and I'm sure you can come up with other points to replace it (do feel free to commit directly to the branch if you want to).
Vercel famously makes a ton of open-source tooling, so I am not really sure what the link is there with what you're saying and why you thought it was a negative thing, it wasn't intended to be one.
There was a problem hiding this comment.
Sounds good! I illustrated how the spirit of those sections should stay here, so let's refocus there.
| ## 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. | ||
|
|
||
| ```bash title="Terminal" | ||
| npx create-nx-workspace --preset=next --ci=skip --e2eTestRunner=none --style=tailwind --nextAppDir=true --nextSrcDir=false --packageManager=pnpm --appName=starter | ||
| npx create-nx-workspace --workspaces --preset=next --ci=skip --e2eTestRunner=none --unitTestRunner=none --style=tailwind --nextAppDir=true --nextSrcDir=false --appName=starter |
There was a problem hiding this comment.
I can see why these changes to start with a JS Workspace would make sense without context. I did it without a Workspace because everyone I've had to help with a migration comes from a place of being misaligned with the JS ecosystem due to the recommendations of the Nx documentation. Without fail, we have to introduce the Workspace first, and then we continue with the rest.
Would you want to take another try at it to make the doc say something to the effect of "If you already are using Workspaces, you can skip steps x, y, and z"? A banner above this code block would likely work great!
There was a problem hiding this comment.
I do feel like inflammatory language like "misaligned with the JS ecosystem" isn't particularly helpful to the discourse. I don't think the countless monorepos out there deriving enormous value from the setup that Nx originally started with (before the prevalence of package manager workspaces) deserve such a derogatory label. We still provide support for this/them, in addition to package manager workspaces. You have to remember your sampling bias here, it is exclusively folks who are already dissatisfied that are going through this with you.
I'm not fully picturing what you're proposing but I think it sounds reasonable, maybe I could take a look at the change if you make it please?
There was a problem hiding this comment.
What you've quoted is not inflammatory language. I can understand that you might not like it, but it's purely a technical comment. If you told me something in Turborepo isn't aligned with the ecosystem in some way, I would thank you and do my best to fix it. The JS ecosystem has aligned on Workspaces and the majority of the subset of Nx users that come to Turborepo don't use them, to their detriment.
You have to remember your sampling bias here, it is exclusively folks who are already dissatisfied that are going through this with you.
I'm well aware of this. This page's contents are specifically written as a collection of their feedback.
There was a problem hiding this comment.
As I'm sure we'd all guess, changes requested! 😄 🎉
Before discussing what we'll need to change, how to change it, etc., I do want to provide what I think is some important context: The reason this document came to be is I've recently been helping with a growing number of migrations from Nx to Turborepo. It was starting to consume too much of my time, so I needed a doc to help bridge the gap.
The reason I share this is that I want folks that land on this PR to know that this guide was written from experience. The common patterns have been fairly clear.
- The "Why switch?" section is a collection of sentiments that were continually repeated by Nx users when I asked about their motivations for migrating. They're in no way something that I came up with. After hearing the same themes enough times, I was comfortable and confident enough to write them down.
- I'll be the first to say that I'm not an Nx expert and, because of that, I couldn't have come up with these reasons myself - even if I'd wanted to.
- The migration steps are the spot where I'd really, really appreciate your feedback, as you'll have more knowledge of what gets lost when unwrapping the plugin layers. Like I said, I'm not the expert on Nx, and I continue to have a hard time gleaning from the docs what specific functionality each plugin contains.
With that background in place, now for the actual PR review! I've addressed the code review itself with comments to this point, so to review the video content:
- In the video, you did a migration from Turborepo to Nx. This document is about the opposite direction, so it's hard to sort out what I'm really meant to get from that part.
- What I took away from it is: Yes, Nx works with JavaScript package manager Workspaces. What I've seen and heard from Nx users is that they don't use it this way because of recommendations in the Nx documentation, and they run into issues because of this.
- If you'd like to have a play with the wording, I can dig that. If it feels like it reads too harsh, that's not my intention and I apologize. Let's work on it! But the core theme of the section needs to remain intact. I can't ignore what real users have been telling me their motivations are.
- What I took away from it is: Yes, Nx works with JavaScript package manager Workspaces. What I've seen and heard from Nx users is that they don't use it this way because of recommendations in the Nx documentation, and they run into issues because of this.
- The demonstration of plugins that you did is what the "more control over source code" section is meant to reference. There's a layer of obfuscation there that I've been repeatedly told by Nx users migrating to Turborepo ends up problematic for their repositories, and so this section again comes from my experience with Nx users looking to migrate.
- Again, if that reads too harshly, happy to make some changes! But, also again, the core intent needs to stay.
- The part discussing pricing of Remote Caching continues to be unclear to me. I described some of my confusion in this comment, but it's worth enumerating how both Turborepo and Nx work here:
- Turborepo's Remote Caching is completely free whether you use it self-hosted or on Vercel.
- We publish an OpenAPI spec for custom Remote Cache servers (human-friendly docs pages are a work-in-progress, will be available here soon - stay tuned!).
- We just released a canary this morning with an improvement for authenticating to self-hosted Remote Caches and I made sure to notify the most popular community maintained one of this.
- If you do choose to use Vercel Remote Cache, its only limitations are for preventing abuse. No one using Vercel Remote Cache in an honest manner comes anywhere near these limits - not even the heaviest user, Vercel Engineering.
- Nx (please correct any of this if wrong) self-hosting documentation's first step is buying a license. While there are qualifications for getting a free license, this does not mean that Remote Caching with Nx is free.
- Self-hosted Remote Caching is effectively paywalled, according to Nx users. What was once free to use is not anymore. Examples include:
- RFC: Pre and Post Run API nrwl/nx#29637 (comment)
- Migrating Nx core to Rust & deprecating custom runners nrwl/nx#28434 (comment)
- The conversations I've had with former Nx users in real life (I would hyperlink, but why isn't real life hyperlink-able?!)
- Self-hosted Remote Caching is effectively paywalled, according to Nx users. What was once free to use is not anymore. Examples include:
- Turborepo's Remote Caching is completely free whether you use it self-hosted or on Vercel.
So! Let's definitely keep this moving forward. A few things to keep the momentum going:
- I'm going to roll a few PRs shortly for wording things that should bring some relief.
- For this PR, let's focus on the comments on the diff first. I think we'll have a clearer picture to work with after those are settled in.
Thank you for working with us on this! Excited for this page to improve.
| @@ -433,7 +366,7 @@ We encourage incremental migration, meaning you will have both of Nx and Turbore | |||
|
|
|||
| ### 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. | |||
| 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. | |||
|
|
|||
| 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](/repo/docs/crafting-your-repository/managing-dependencies) to learn more. | |||
There was a problem hiding this comment.
| 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](/repo/docs/crafting-your-repository/managing-dependencies) to learn more. | |
| Historically, Nx has recommended installing all dependencies in the root of the repository, making all dependencies available to all packages in the workspace. If you followed this guidance, 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](/repo/docs/crafting-your-repository/managing-dependencies) to learn more. |
|
It's disappointing that you are doubling down on points which were directly proven to be false. Rushing #10017 through without discussion was not a good thing and your justification simply does not make sense to me.
Clearly, a "Why Switch?" section should be an objective "bigging up" of your own technology and its advantages, not an amplification of unverifiable, negative anecdotes from a tiny subset of users who have already decided to switch away from ours. I prove to you directly on this PR in my video that with no modifications (other than a like for like root level JSON file), Nx works perfectly based on Turborepo's self-defined best practices. Promoting anything else is objectively not right. I feel deeply sorry to any users we let down enough for them to feel the need to switch, but that is also ultimately their choice and their right. This is self-evidently a documentation and clarity of communication issue and we are taking it very seriously internally and many guides are actively being updated to make sure the reflect the reality, such as this one about dependency management: https://nx.dev/concepts/decisions/dependency-management Again, I am grateful to you for acting as a forcing function for us to improve in this area, but please reconsider your positioning here. |
|
I will get back to you shortly on the Powerpack side, it warrants its own discussion |
|
#10017 merged while #10019 was open. I just didn't do them as one PR because my baby interrupted me. I had the one-liner change in #10017 ready, so I just put it up real quick, knowing I had #10019 prepared to make some corrections, according to your feedback. #10019 is based on your feedback, filling in several of my knowledge gaps about Nx. If there are more and you'd like to address them, you're more than welcome to in this PR. My only ask is that you maintain the intent of the sections you'd like to edit, as they're based on real user feedback. As much as I'd like to make you happy, I feel a deeper sense of responsibility to the Turborepo and about-to-be-Turborepo communities and the content of this page will continue to serve that group.
We disagree about the purpose of this section. I imagine someone searching "migrate from nx" in a search tool, and ending up on this page. Objectively, we have no way of knowing whether they are entirely convicted in their decision already, or are looking for confirmation about an idea they had. In the case that they're uncertain, its important that this content bring them clarity and conviction around what they were considering in a truthful way. Providing anecdata from others who are in the same position, same headspace as them in the past, is worthwhile and important, despite the fact that it might not be suited to your goals.
I still don't know what the migration from Turborepo to Nx was meant to show about the content of this document. This page is for migrating from Nx to Turborepo. What you're describing is orthogonal.
I don't mean for this to sound dismissive, but you may want to save your efforts to the discussions with your users I've linked above. Since you've opened this PR, I've had several more Nx users reach out to me to send me messages about this PR and the conversation on it. I think it will be more fitting to DM them to you on Twitter, so I'll do that. Altogether, I'd encourage you to focus on the code in this PR so we can ship any more updates you'd like. To restate, the general intent and focus of the page and its sections won't change to lose their meaning, so you may want to rebase and work through the page again with the new context and content. |
Description
Understanding.Nx.and.Turborepo.differences.and.correcting.the.sites.inaccuracies.mp4
Backup Loom Link incase the embedded video fails:
🎥 https://www.loom.com/share/83aa7b7de68740f7ace6f3b2bbdd3291
Hi Folks 👋
James here, Director of Engineering at Nx.
As I clearly state in the video, I am not looking to figure out blame or anything like that, but it's important that we always represent each other's tools in good faith. Currently your "migrating from Nx" guide contains multiple fundamental inaccuracies about Nx.
I've therefore recorded the above comprehensive, personal, walkthrough of the changes and why they are being made, and I accompany all points with live demos of Nx and Turborepo in action to make sure there are no further misunderstandings.
I'm sorry about that length (maybe you can watch on 2x speed 😄), but again, I think there is a significant amount of demonstrably false information currently, and I wanted to make sure we're all on the same page about what needs to change.
I'll happily incorporate any suggested tweaks based on ordering/writing style/tone of voice, please just let me know, and as per the video, please know that the door is always open for any corresponding corrections in our own materials or open-source benchmarks. We strive to keep them up to date and believe they are currently in an accurate state, but if you find anything please feel free to ping me.
Cheers!