content(userland-migration): make up to date
#8053
Conversation
AugustinMauroy
added
content
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
There was a problem hiding this comment.
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 |
|
|
||
| ## `import-assertions-to-attributes` | ||
|
|
||
| During the process of TC39 standardization, the `import assert` feature was introduced to allow importing [JSON modules](https://tc39.es/proposal-json-modules/) but during the during the transition to stage 4, the `assert` keyword was removed and replaced with an `with` attribute on the `import` statement. |
There was a problem hiding this comment.
The phrase 'but during the during the transition' contains a duplicated word 'during'. It should be 'but during the transition'.
| During the process of TC39 standardization, the `import assert` feature was introduced to allow importing [JSON modules](https://tc39.es/proposal-json-modules/) but during the during the transition to stage 4, the `assert` keyword was removed and replaced with an `with` attribute on the `import` statement. | |
| During the process of TC39 standardization, the `import assert` feature was introduced to allow importing [JSON modules](https://tc39.es/proposal-json-modules/) but during the transition to stage 4, the `assert` keyword was removed and replaced with an `with` attribute on the `import` statement. |
Copilot uses AI. Check for mistakes.
|
|
||
| So in [node.js v22](https://nodejs.org/fr/blog/release/v22.0.0#other-notable-changes), the `import assert` feature was removed and you need to use the `with` attribute instead. | ||
|
|
||
| Also note that the `with` keyword as been introduce in [node.js v18.20](https://nodejs.org/fr/blog/release/v18.20.0#added-support-for-import-attributes) but it was not mandatory until v22. |
There was a problem hiding this comment.
The word 'introduce' should be 'introduced' (past participle form) and 'as' should be 'has'.
| Also note that the `with` keyword as been introduce in [node.js v18.20](https://nodejs.org/fr/blog/release/v18.20.0#added-support-for-import-attributes) but it was not mandatory until v22. | |
| Also note that the `with` keyword has been introduced in [node.js v18.20](https://nodejs.org/fr/blog/release/v18.20.0#added-support-for-import-attributes) but it was not mandatory until v22. |
Copilot uses AI. Check for mistakes.
|
|
||
| When you want to [run typescript natively in Node.js](/learn/typescript/run-natively), you need to have a correct "specifiers" in your [imports statements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import). | ||
|
|
||
| To run this codemdod, you have to use this command: |
There was a problem hiding this comment.
The word 'codemdod' should be 'codemod'.
| To run this codemdod, you have to use this command: | |
| To run this codemod, you have to use this command: |
Copilot uses AI. Check for mistakes.
| npx codemod@latest run correct-ts-specifiers | ||
| ``` | ||
|
|
||
| > **Note:** This codemod use "legacy" codemod CLI, if you wan to undersant more about it, you can read the [new codemod CLI announcement](https://codemod.com/blog/new-codemod-cli). |
There was a problem hiding this comment.
Multiple spelling errors: 'use' should be 'uses', 'wan' should be 'want', and 'undersant' should be 'understand'.
| > **Note:** This codemod use "legacy" codemod CLI, if you wan to undersant more about it, you can read the [new codemod CLI announcement](https://codemod.com/blog/new-codemod-cli). | |
| > **Note:** This codemod uses the "legacy" codemod CLI. If you want to understand more about it, you can read the [new codemod CLI announcement](https://codemod.com/blog/new-codemod-cli). |
Copilot uses AI. Check for mistakes.
|
|
||
| ## Feedback | ||
|
|
||
| If you have any tools that you would like to be handle by userland-migrations, please open an issue on the [Node.js Userland Migrations repository](https://github.com/nodejs/userland-migrations/issues). |
There was a problem hiding this comment.
The phrase 'to be handle' should be 'to be handled'.
| If you have any tools that you would like to be handle by userland-migrations, please open an issue on the [Node.js Userland Migrations repository](https://github.com/nodejs/userland-migrations/issues). | |
| If you have any tools that you would like to be handled by userland-migrations, please open an issue on the [Node.js Userland Migrations repository](https://github.com/nodejs/userland-migrations/issues). |
Copilot uses AI. Check for mistakes.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #8053 +/- ##
==========================================
+ Coverage 72.96% 73.02% +0.05%
==========================================
Files 95 95
Lines 8324 8336 +12
Branches 215 215
==========================================
+ Hits 6074 6087 +13
+ Misses 2249 2248 -1
Partials 1 1 ☔ View full report in Codecov by Sentry. |
There was a problem hiding this comment.
What's the point of this file?
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
yeah it's solve that. But why I'm doing this pr is to use your cool UI to show our codemod
|
|
||
| # Userland Migrations | ||
|
|
||
| Node.js provides migrations for "userland" (what you write vs node's own) source-code to facilitate adoption of new features and upgrading source-code affected by breaking changes. These are done in collaboration with [`codemod`](https://docs.codemod.com/introduction), who also work with other major projects like Next.js, React, and Tailwind. Node.js's migrations live in the [`nodejs/userland-migrations`](https://github.com/nodejs/userland-migrations) repository and are overseen by the `@nodejs/userland-migrations` team. |
There was a problem hiding this comment.
| Node.js provides migrations for "userland" (what you write vs node's own) source-code to facilitate adoption of new features and upgrading source-code affected by breaking changes. These are done in collaboration with [`codemod`](https://docs.codemod.com/introduction), who also work with other major projects like Next.js, React, and Tailwind. Node.js's migrations live in the [`nodejs/userland-migrations`](https://github.com/nodejs/userland-migrations) repository and are overseen by the `@nodejs/userland-migrations` team. | |
| Node.js provides migrations for "userland"(anything not included in the `node` executable itself) to facilitate the adoption of new features and breaking changes. These are done in collaboration with [Codemod](https://docs.codemod.com/introduction), a company that specializes in xyz. | |
| For Node.js, migrations live in https://github.com/nodejs/userland-migrations, and are overseen by the project itself. |
There was a problem hiding this comment.
this paragraph was originally written by @JakobJingleheimer so let's see his opinon
There was a problem hiding this comment.
some alternative:
Node.js offers migrations for "userland" code (anything outside the node executable) to help adopt new features and handle breaking changes. These are built in collaboration with Codemod, a company focused on making it easy to build, share, and run codemods.
| <!-- | ||
| maintainer node: https://codemod.link/nodejs-official is pointing to legacy codemod registry | ||
| it's will point to new new one once codemod change the redirection of the short link | ||
| --> |
There was a problem hiding this comment.
I don't like that we have a maintainer note, can we can an ETA on this change?
There was a problem hiding this comment.
There was a problem hiding this comment.
Agreed with Aviv. we don’t need to have such a note.
We, the Codemod team, will update the same shortlink on August 8, 2025 to point to the new registry.
(Besides link usage analytics, a key reason we use shortlinks is to avoid the maintenance overhead of updating links for users.)
cc @mohebifar
| it's will point to new new one once codemod change the redirection of the short link | ||
| --> | ||
|
|
||
| Official migrations are published under the `@nodejs` namespace within the [codemod registry](https://codemod.link/nodejs-official). These have been reviewed and/or authored by Node.js members. There are also unofficial migrations available which have not been reviewed by Node.js. |
There was a problem hiding this comment.
| Official migrations are published under the `@nodejs` namespace within the [codemod registry](https://codemod.link/nodejs-official). These have been reviewed and/or authored by Node.js members. There are also unofficial migrations available which have not been reviewed by Node.js. | |
| Official migrations (migrations that have been developed with Node.js project oversight) are published under the [`@nodejs`][...] scope within the [Codemod registry][...]. |
|
|
||
| Official migrations are published under the `@nodejs` namespace within the [codemod registry](https://codemod.link/nodejs-official). These have been reviewed and/or authored by Node.js members. There are also unofficial migrations available which have not been reviewed by Node.js. | ||
|
|
||
| ## Our goal |
There was a problem hiding this comment.
| ## Our goal | |
| ## Goal |
| First our goal is to help you to migrate your codebase to the latest Node.js version. We want to make it easier for you to adopt new features, deprecations, and breaking changes. In summary, we want to help you to migrate your codebase to the latest Node.js version. | ||
|
|
||
| Second, we want to help you to adopt native Node.js features that are already available in the ecosystem. For example, if you are using a library that provides a feature that is already available in Node.js, we want to help you to migrate to the native Node.js feature. |
There was a problem hiding this comment.
| First our goal is to help you to migrate your codebase to the latest Node.js version. We want to make it easier for you to adopt new features, deprecations, and breaking changes. In summary, we want to help you to migrate your codebase to the latest Node.js version. | |
| Second, we want to help you to adopt native Node.js features that are already available in the ecosystem. For example, if you are using a library that provides a feature that is already available in Node.js, we want to help you to migrate to the native Node.js feature. | |
| The Node.js Userland Migrations team seeks to help developers migrate their codebases to the latest Node.js versions, making it easier to handle deprecations, new features, and breaking changes. |
| ```bash displayName="npm" | ||
| npx codemod@next <codemod-name> | ||
| ``` |
There was a problem hiding this comment.
Why ? On download we explain how to install yarn pnpm so why not on this page show them
There was a problem hiding this comment.
Because if we showcase them, we are responsible for making that code work for our users. We are responsible for npm, not the other package managers
There was a problem hiding this comment.
There's no need to add an article for each version upgrade. IMO such articles should be blog posts / on the Codemod repository
There was a problem hiding this comment.
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 not that we cannot touch to release note
There was a problem hiding this comment.
That's very different. A "doc" is different than an "article". The docs change from version to version. Articles here do not.
Olay i had opened the pr to have review on structure/aproeach |
| npx codemod@latest run correct-ts-specifiers | ||
| ``` | ||
|
|
||
| > **Note:** This codemod use "legacy" codemod CLI, if you wan to undersant more about it, you can read the [new codemod CLI announcement](https://codemod.com/blog/new-codemod-cli). |
There was a problem hiding this comment.
We can safely remove this "Note" section. it adds unnecessary confusion. Users don’t need to know which CLI is being used. When they run npx codemod@latest <codemod-name>, we automatically choose the right one behind the scenes. Both the new and old CLIs are wrapped and fully backward compatible. cc @mohbifar
|
|
||
| # Userland Migrations | ||
|
|
||
| Node.js provides migrations for "userland" (what you write vs node's own) source-code to facilitate adoption of new features and upgrading source-code affected by breaking changes. These are done in collaboration with [`codemod`](https://docs.codemod.com/introduction), who also work with other major projects like Next.js, React, and Tailwind. Node.js's migrations live in the [`nodejs/userland-migrations`](https://github.com/nodejs/userland-migrations) repository and are overseen by the `@nodejs/userland-migrations` team. |
There was a problem hiding this comment.
some alternative:
Node.js offers migrations for "userland" code (anything outside the node executable) to help adopt new features and handle breaking changes. These are built in collaboration with Codemod, a company focused on making it easy to build, share, and run codemods.
Description
Reflect current status of the
userland-migrationinitiative. Plus show new codemods.Related Issues
No related issues
Check List
pnpm formatto ensure the code follows the style guide.pnpm testto check if all tests are passing.pnpm buildto check if the website builds without errors.