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

AugustinMauroy · 2025-07-30T16:20:00Z

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 · 2025-07-30T16:20:05Z

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

Project	Deployment	Preview	Updated (UTC)
nodejs-org	Ready	Preview	Sep 26, 2025 7:35am

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

apps/site/pages/en/blog/migrations/v20-to-v22.mdx

apps/site/pages/en/learn/userland-migrations/ecosystem.md

codecov · 2025-07-30T16:21:17Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.65%. Comparing base (0b90e2c) to head (464acd9).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8053      +/-   ##
==========================================
+ Coverage   76.56%   76.65%   +0.09%     
==========================================
  Files         115      115              
  Lines        9602     9622      +20     
  Branches      323      322       -1     
==========================================
+ Hits         7352     7376      +24     
+ Misses       2249     2245       -4     
  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.

apps/site/pages/en/learn/userland-migrations/ecosystem.md

apps/site/pages/en/learn/userland-migrations/introduction.md

apps/site/pages/en/learn/userland-migrations/v14-to-v16.md

AugustinMauroy · 2025-07-30T16:37:52Z

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

apps/site/pages/en/learn/userland-migrations/ecosystem.md

apps/site/pages/en/learn/userland-migrations/introduction.md

AugustinMauroy · 2025-08-13T10:37:04Z

@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 · 2025-08-13T13:49:40Z

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 · 2025-08-20T07:50:38Z

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 · 2025-08-24T10:16:25Z

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

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

ovflowd · 2025-08-25T17:51:14Z

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 · 2025-08-25T19:52:36Z

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 · 2025-08-26T20:20:11Z

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

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 · 2025-08-26T20:23:38Z

@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 · 2025-08-26T20:24:27Z

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

AugustinMauroy · 2025-08-26T20:30:26Z

@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 · 2025-08-26T20:35:13Z

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 · 2025-08-27T00:38:30Z

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 · 2025-08-27T00:41:28Z

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.

AugustinMauroy · 2025-09-26T07:31:44Z

Okay friend, I redid everything afterwards:

the discussion between Claudio and Alex
the sync meeting between Jacob and Alex
and the userland migrations meeting

avivkeller · 2025-09-29T20:21:53Z

Okay, during today's meeting, we discussed moving forward with, as it relates to this PR,

Putting Migration guides in the Blog.
Putting concepts related to migrations in Learn.

avivkeller · 2025-09-29T20:23:07Z

apps/site/pages/en/blog/migrations/v12-to-v14.mdx

+<AlertBox level="warning" title="!">
+  This article cover a part of the migration from Node.js v12 to v14. The
+  userland migrations team is working on more codemods to help you with the
+  migration.
+</AlertBox>


Does this really have to be an alert box?

avivkeller

Started review, same tropes throughout the articles.

Thank you!

avivkeller · 2025-09-29T20:23:20Z

apps/site/pages/en/blog/migrations/v12-to-v14.mdx

+
+This page provides a list of codemods to help you migrate your code from Node.js v12 to v14.
+
+## `util-print-to-console-log`


Let's link the package in the title

avivkeller · 2025-09-29T20:26:01Z

apps/site/pages/en/blog/migrations/v12-to-v14.mdx

+This recipe transforms the usage of log functions from util, `print`, `puts`, `debug`, `error` to use `console.log()` or `console.error()`.
+
+So this codemod handle [DEP0026](https://nodejs.org/api/deprecations.html#DEP0026), [DEP0027](https://nodejs.org/api/deprecations.html#DEP0027), [DEP0028](https://nodejs.org/api/deprecations.html#DEP0028) and [DEP0029](https://nodejs.org/api/deprecations.html#DEP0029).


Suggested change

This recipe transforms the usage of log functions from util, `print`, `puts`, `debug`, `error` to use `console.log()` or `console.error()`.

So this codemod handle [DEP0026](https://nodejs.org/api/deprecations.html#DEP0026), [DEP0027](https://nodejs.org/api/deprecations.html#DEP0027), [DEP0028](https://nodejs.org/api/deprecations.html#DEP0028) and [DEP0029](https://nodejs.org/api/deprecations.html#DEP0029).

This recipe transforms calls of various now-deprecated `node:util` log functions into the modern alternative, `console.log` and `console.error`:

- ([DEP](...)) [`func`](...) - `console.XYZ`

- ...

avivkeller · 2025-09-29T20:27:43Z

apps/site/pages/en/blog/migrations/v14-to-v16.mdx

+In Node.js v16, the `createRequire` function was introduced to allow you to create a `require` function that can be used in ESM modules. This codemod will help you replace the old `createRequireFromPath` function with the new `createRequire` function.
+
+So this codemod handle [DEP0130](https://nodejs.org/api/deprecations.html#DEP0130).


Suggested change

In Node.js v16, the `createRequire` function was introduced to allow you to create a `require` function that can be used in ESM modules. This codemod will help you replace the old `createRequireFromPath` function with the new `createRequire` function.

So this codemod handle [DEP0130](https://nodejs.org/api/deprecations.html#DEP0130).

Node.js v16 replaced the [`createRequireFromPath`](...), deprecated in [DEP](...), with the modern [`createRequire`](...) function. This codemod replaces calls of the deprecated function with the modern alternative mentioned.

avivkeller · 2025-09-29T20:28:23Z

apps/site/pages/en/blog/migrations/v14-to-v16.mdx

+```js displayName="Before"
+import { createRequireFromPath } from 'node:module';
+
+// Using createRequireFromPath


Is this comment needed, or is it implied?

avivkeller · 2025-09-29T20:29:00Z

apps/site/mdx/components.mjs

  blockquote: Blockquote,
  pre: MDXCodeBox,
  img: MDXImage,
+  // Allow the writter to use an pretty alert box


Suggested change

// Allow the writter to use an pretty alert box

// Renders a CSS-enhanced Alert Box

avivkeller · 2025-09-29T20:29:47Z

apps/site/pages/en/blog/migrations/v14-to-v16.mdx

+The `process.mainModule` property was deprecated in favor of `require.main`. This codemod will help you replace the old `process.mainModule` usage with the new `require.main` usage.
+
+So the codemod handle [DEP0138](https://nodejs.org/api/deprecations.html#DEP0138).


Suggested change

The `process.mainModule` property was deprecated in favor of `require.main`. This codemod will help you replace the old `process.mainModule` usage with the new `require.main` usage.

So the codemod handle [DEP0138](https://nodejs.org/api/deprecations.html#DEP0138).

The [`process.mainModule`](...) property was deprecated ([DEP](...)) in favor of [`require.main`](...). This codemod replaces calls of the deprecated function with the modern alternative mentioned.

avivkeller · 2025-09-29T20:30:30Z

apps/site/pages/en/blog/migrations/v22-to-v24.mdx

@@ -0,0 +1,55 @@
+---


Let's wait for v24 to officially get it's LTS badge

AugustinMauroy requested review from JakobJingleheimer and Copilot July 30, 2025 16:20

AugustinMauroy requested a review from a team as a code owner July 30, 2025 16:20

AugustinMauroy added content Issues/pr concerning content learn Issues/pr concerning the learn section labels Jul 30, 2025

Copilot AI reviewed Jul 30, 2025

View reviewed changes

avivkeller requested changes Jul 30, 2025

View reviewed changes

AugustinMauroy marked this pull request as draft July 30, 2025 16:37

alexbit-codemod reviewed Aug 1, 2025

View reviewed changes

apps/site/pages/en/learn/userland-migrations/ecosystem.md Outdated Show resolved Hide resolved

apps/site/pages/en/learn/userland-migrations/introduction.md Outdated Show resolved Hide resolved

vercel bot deployed to Preview August 13, 2025 10:10 View deployment

vercel bot deployed to Preview August 13, 2025 10:26 View deployment

vercel bot deployed to Preview August 13, 2025 10:44 View deployment

vercel bot deployed to Preview August 24, 2025 10:08 View deployment

AugustinMauroy marked this pull request as ready for review August 24, 2025 10:30

AugustinMauroy force-pushed the content(`userland-migration`) branch from 5a6d2f6 to e98d32d Compare August 26, 2025 19:56

vercel bot deployed to Preview August 26, 2025 19:58 View deployment

avivkeller added the web-agenda label Aug 26, 2025

ovflowd requested changes Aug 27, 2025

View reviewed changes

ovflowd added the blocked label Aug 27, 2025

avivkeller mentioned this pull request Sep 2, 2025

Meeting 9/8/2025 nodejs/web-team#39

Closed

2 tasks

AugustinMauroy mentioned this pull request Sep 17, 2025

Meeting ? nodejs/userland-migrations#209

Closed

avivkeller mentioned this pull request Sep 21, 2025

Node.js Web Team Meeting 2025-09-29 nodejs/web-team#43

Open

vercel bot deployed to Preview September 22, 2025 07:19 View deployment

vercel bot deployed to Preview September 26, 2025 07:09 View deployment

AugustinMauroy added 9 commits September 26, 2025 09:14

content(userland-migration): make up to date

5d7b7d7

Update introduction.md

d398f90

update

154245b

Update navigation.json

010996b

Update

99f368e

use correct casing

17bcae9

update

81ee06b

update after meeting

6d86268

fix link

a009faf

AugustinMauroy force-pushed the content(`userland-migration`) branch from 5159749 to a009faf Compare September 26, 2025 07:14

vercel bot deployed to Preview September 26, 2025 07:16 View deployment

feat(mdx): add alertBox

c7d66ab

vercel bot deployed to Preview September 26, 2025 07:22 View deployment

fix

464acd9

vercel bot deployed to Preview September 26, 2025 07:35 View deployment

avivkeller removed the web-agenda label Sep 29, 2025

avivkeller reviewed Sep 29, 2025

View reviewed changes


		This page provides a list of codemods to help you migrate your code from Node.js v12 to v14.

		## `util-print-to-console-log`

		This recipe transforms the usage of log functions from util, `print`, `puts`, `debug`, `error` to use `console.log()` or `console.error()`.

		So this codemod handle [DEP0026](https://nodejs.org/api/deprecations.html#DEP0026), [DEP0027](https://nodejs.org/api/deprecations.html#DEP0027), [DEP0028](https://nodejs.org/api/deprecations.html#DEP0028) and [DEP0029](https://nodejs.org/api/deprecations.html#DEP0029).

		In Node.js v16, the `createRequire` function was introduced to allow you to create a `require` function that can be used in ESM modules. This codemod will help you replace the old `createRequireFromPath` function with the new `createRequire` function.

		So this codemod handle [DEP0130](https://nodejs.org/api/deprecations.html#DEP0130).

	// Allow the writter to use an pretty alert box
	// Renders a CSS-enhanced Alert Box

		The `process.mainModule` property was deprecated in favor of `require.main`. This codemod will help you replace the old `process.mainModule` usage with the new `require.main` usage.

		So the codemod handle [DEP0138](https://nodejs.org/api/deprecations.html#DEP0138).

Uh oh!

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

AugustinMauroy commented Jul 30, 2025

Description

Related Issues

Check List

Uh oh!

vercel bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

avivkeller left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AugustinMauroy commented Jul 30, 2025

Uh oh!

Uh oh!

Uh oh!

AugustinMauroy commented Aug 13, 2025

Uh oh!

avivkeller commented Aug 13, 2025

Uh oh!

JakobJingleheimer commented Aug 20, 2025

Uh oh!

AugustinMauroy commented Aug 24, 2025

Uh oh!

ovflowd commented Aug 25, 2025

Uh oh!

AugustinMauroy commented Aug 25, 2025

Uh oh!

AugustinMauroy commented Aug 26, 2025

Uh oh!

avivkeller commented Aug 26, 2025

Uh oh!

avivkeller commented Aug 26, 2025

Uh oh!

AugustinMauroy commented Aug 26, 2025

Uh oh!

avivkeller commented Aug 26, 2025

Uh oh!

ovflowd commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ovflowd commented Aug 27, 2025

Uh oh!

ovflowd left a comment

Choose a reason for hiding this comment

Uh oh!

AugustinMauroy commented Sep 26, 2025

Uh oh!

avivkeller commented Sep 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avivkeller left a comment

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

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

vercel bot commented Jul 30, 2025 •

edited

Loading

codecov bot commented Jul 30, 2025 •

edited

Loading

ovflowd commented Aug 27, 2025 •

edited

Loading