content(userland-migration): make up to date

[AugustinMauroy]

Description

Reflect current status of the userland-migration initiative. Plus show new codemods.

Related Issues

No related issues

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run pnpm format to ensure the code follows the style guide.
• I have run pnpm test to check if all tests are passing.
• I have run pnpm build to check if the website builds without errors.
• NA I've covered new added functionality with unit tests if necessary.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
nodejs-org	Ready	Preview	Aug 26, 2025 7:58pm

[Copilot]

Pull Request Overview

Updates the userland-migration documentation to reflect current status and showcase new codemods for Node.js version migrations and ecosystem transitions.

• Reorganizes navigation structure from "migrations" to "userland-migrations" for consistency
• Adds comprehensive documentation for v20-to-v22 and v14-to-v16 migration codemods
• Introduces ecosystem migration documentation for transitioning from external tools to native Node.js features

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/i18n/src/locales/en.json	Updates navigation labels and adds new migration page entries
apps/site/pages/en/learn/userland-migrations/v20-to-v22.md	Documents import assertions to attributes codemod for Node.js v22 migration
apps/site/pages/en/learn/userland-migrations/v14-to-v16.md	Documents createRequire and rmdir codemods for Node.js v16 migration
apps/site/pages/en/learn/userland-migrations/introduction.md	Enhanced introduction with comprehensive usage guide and best practices
apps/site/pages/en/learn/userland-migrations/ecosystem.md	Documents TypeScript specifier correction codemod for ecosystem migration
apps/site/pages/en/learn/migrations/introduction.md	Removes old migration documentation file
apps/site/navigation.json	Updates navigation structure to use new userland-migrations path and adds new pages

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.92%. Comparing base (84c25ab) to head (e98d32d).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8053      +/-   ##
==========================================
+ Coverage   75.89%   75.92%   +0.03%     
==========================================
  Files         112      112              
  Lines        9433     9449      +16     
  Branches      303      303              
==========================================
+ Hits         7159     7174      +15     
- Misses       2273     2274       +1     
  Partials        1        1              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[avivkeller]

Did a cursory review. There's definitely a lot of work to be done before this can land, so I'm blocking for now.

[avivkeller]

What's the point of this file?

[AugustinMauroy]

Second part of your goal like. It's will host all codemod related to ecosystem not specific node version

• jest-to-node-test (pr opened)
• mocha-to-node-test (issue opened)
• axios-to-fetch (in my brain)
• correct-ts-specifiers (released)

[avivkeller]

Can we outsource this list, since it'll change often, i.e. in the main file, have a paragraph about "Ecosystem" upgrades, and "Migration" upgrades, with a link to the list of each in the Codemod repository? This'll also resolve my concern at #8053 (comment)

[AugustinMauroy]

yeah it's solve that. But why I'm doing this pr is to use your cool UI to show our codemod

[avivkeller]

There's no need to add an article for each version upgrade. IMO such articles should be blog posts / on the Codemod repository

[AugustinMauroy]

react make it as a blog post https://react.dev/blog/2024/04/25/react-19-upgrade-guide
next as a doc page https://nextjs.org/docs/app/guides/upgrading/version-15
fastify do it as doc https://fastify.dev/docs/latest/Guides/Migration-Guide-V3/

So IMO here it's goo area. Also note that we cannot touch to release note

[avivkeller]

That's very different. A "doc" is different than an "article". The docs change from version to version. Articles here do not.

[avivkeller]

See #8053 (comment)

[AugustinMauroy]

Did a cursory review. There's definitely a lot of work to be done before this can land, so I'm blocking for now.

Olay i had opened the pr to have review on structure/aproeach

[AugustinMauroy]

@avivkeller I have a compromise to propose. We will proceed with this file structure even if you are not satisfied with it. We will then reopen issue #7267 and find a long-term solution for where to store these documents.

[avivkeller]

I'm still strongly -1 on articles for specific Codemods. Those should be blog posts, if anything.

cc @nodejs/nodejs-website @nodejs/marketing for opinions

[JakobJingleheimer]

I'm still strongly -1 on articles for specific Codemods. Those should be blog posts, if anything.

cc @nodejs/nodejs-website @nodejs/marketing for opinions

If I'm understanding right, the current article(s) are listing specific codemods as part of a major node migration, which means that list will be frozen once complete. That seems okay to me, but perhaps redundant: I would instead just list/link to the major migration recipe, which will itself list the individual migrations anyway.

P.S. I think we definitely should not statically list all migrations available. That would be an untenable maintenance burden, and we already have tools (github, the codemod registry, and perhaps others) that do it well already.

[AugustinMauroy]

@avivkeller other solution using doc-kit with web generator on userland-migration repo so:

1. we will have search + super UI
2. document will lived in same repo than source so easy to maintain
3. we can point migration.nodejs.org on nodejs.github.io/userland-migrations

[ovflowd]

I'm neutral here, but agree that codemods are something more "temporal", so I agree with the notion of this being better suited for a blog post?

[AugustinMauroy]

I'm neutral here, but agree that codemods are something more "temporal", so I agree with the notion of this being better suited for a blog post?

In theory, yes. But in our case, it doesn't work because a blog post is read once by the user when it is published (from a post on the RSS feed network). But here, we haven't yet completed all the migrations to cover a complete version, so once they've read it, they won't come back to the post even if new codemod is added to it.

And frankly, we need visibility to help with adoption so that we can then get feedback.

[AugustinMauroy]

Hello @nodejs/tsc, I would like to hear your opinion on the situation.

This PR updates the resource on userland-migrations to include everything that has been produced by the initiative and introduces a new page.
For historical context, the userland-migrations initiative was launched by Jacob after the Dublin Collab Summit in 2024. It aims to provide codemods to handle deprecations, breaking changes, or feature adoption. That is why the issue #7267 was created to determine where we should put these resources. It was decided that the learn section would be the right place.

And @avivkeller blocks the idea with the following argument I am linking to the message so as not to paraphrase it

• content(userland-migration): make up to date #8053 (comment)
• content(userland-migration): make up to date #8053 (comment)

So the question that arises is, "Where should we put the migration guides?"

Option 1: Learn section
Simply what this pr offers

Option 2: blog category
Have a dedicated category and keep the same md files.
But the downside is that the posts will have to change when we cover more deprecation. And the concept of a blog post is more about having a document that is posted online and does not change, like a newspaper article. My understanding of the life cycle of a post is that it is posted and shared on social media, then readers read it, and it is rare that we reread a post.

Option 3: dedicated section
I think this is ideal. It would be to have a new section next to About and Learn that covers all migrations. And that solves all the problems (IMO).
But the problem with this approach is that it will fill up the navigation bar, which is already quite full.

Option 4: dedicated website
The idea would be to have migrations.nodejs.org and the sources would be on the userland-migration repo. The host would be done with GH pages and the DANS would point to nodejs.github.io/userland-migration. And to build it, we would use doc-kit, the tool that the website team created for the redesign of the API doc.
The problem here is that it adds a new domain name and is completely separate, which is the opposite of the initial idea of highlighting the initiative. What's more, it adds extra maintenance.
For me, this is the worst approach.

[avivkeller]

@AugustinMauroy in the future, before escalating to the technical steering committee, we can always have a web team meeting.

However, I maintain my stance that these should not be articles. An article for every code mod released is not a viable solution. Rather, I think, a single article linking to the code mod repository, where those lists can be maintained is better.

A code mod here and there could also be a blog post, again, without the need of individual learn articles for specific code mods.

[avivkeller]

A fifth option, that is, have a single learn articles explaining the code mods, and linking to the dedicated repository, would best, imo.

[AugustinMauroy]

@AugustinMauroy in the future, before escalating to the technical steering committee, we can always have a web team meeting.

FYI: I first asked Ruy (because he speaks French, to avoid the language barrier) if it was worth pinging the TSC. And I also didn't add it to the TSC agenda for a formal vote, just to ask for their opinion/feelings.

Furthermore, if I am not mistaken, at the moment the website team is not responsible for the content, so it makes sense to me not to put it in our agenda.

without the need of individual learn articles for specific code mods.

I don't get what you mean on this point. I don't think I wrote an article per codemod. I wrote migration guides per version and one for the ecosystem.

[avivkeller]

Furthermore, if I am not mistaken, at the moment the website team is not responsible for the content, so it makes sense to me not to put it in our agenda.

The website does not maintain content, however, we do have experience with it. A website team meeting could be a useful space to gather feedback before escalating things to the larger project. I’m not saying it was wrong to bring this to the TSC- that’s completely your call. I just wanted to suggest that, in the future, discussing it in a website team meeting could be another option.

I don't get what you mean on this point. I don't think I wrote an article per codemod. I wrote migration guides per version and one for the ecosystem.

Still, those are still documenting mutable content. Learn articles should, for the most part, be immutable (i.e. things that don't rely on changing information, such as Node.js versions). Migration guides are mutable, since they refer to this changing data, thus, they are more suited for a blog post, imo.

[ovflowd]

I actually have a different perspective here—this isn’t really a “content” issue. We’re not evaluating the content itself, but rather where it belongs, which makes it a matter of structure. I agree that this shouldn’t be a Learn article, a dedicated section, or even its own blog category. It should just be placed under an existing blog category, and that’s it.

I’d even argue that codemods—or tutorials for codemods—don’t really belong on the Node.js website at all. The only context where they make sense is in relation to upgrading. In that case, they should be included directly in the release blog posts for each version, since those posts are explicitly tied to upgrading (from one version to another, or from old patterns to new ones). If we go that route, the discussion should involve @.nodejs/releasers.

I’m not against codemods themselves, but they don’t really qualify as “Learn Node.js” content, nor do they warrant their own section of the site. What I would support is a small reference, like an alert saying: “Want to conveniently migrate to new Node.js features? Check out Node.js Codemods”—which could link to a third-party site (Codemod’s website) that maintains a collection of Node.js codemods.

[ovflowd]

Regarding the ping to @nodejs/tsc, I don’t see why that’s necessary. Why would the TSC need to get involved in this project? There’s no real escalation required here—unless you’re specifically trying to escalate it, which in my view is unnecessary. This is something we can absolutely resolve between ourselves.

If it were escalated to the TSC, I’m fairly certain they’d just defer the decision back to me and @bmuenzenmeyer anyway (though I could be wrong).

And I also didn’t add it to the TSC agenda for a formal vote, just to ask for their opinion/feelings.

A formal vote would be overkill. Those should be reserved for genuinely extreme situations. What it feels like here is: “I disagree with you, so I’ll bypass our regular collaboration process and hope the TSC disagrees with @avivkeller and overrules his stance.”

[ovflowd]

Blocking—not because of the content (which is great, and I really appreciate the work you all put into it 🙇).

The concern is about where this should live on our website, in what format, and whether it should even be hosted here at all.

It’s already on our team’s agenda, so we’ll be discussing it soon.