diff --git a/apps/site/navigation.json b/apps/site/navigation.json index cfc6114362475..db9050cdc7d93 100644 --- a/apps/site/navigation.json +++ b/apps/site/navigation.json @@ -332,12 +332,24 @@ } } }, - "migrations": { - "label": "components.navigation.learn.migrations.links.migrations", + "userland-migrations": { + "label": "components.navigation.learn.userland-migrations.links.userland-migrations", "items": { "introduction": { - "link": "/learn/migrations/introduction", - "label": "components.navigation.learn.migrations.links.introduction" + "link": "/learn/userland-migrations/introduction", + "label": "components.navigation.learn.userland-migrations.links.introduction" + }, + "ecosystem": { + "link": "/learn/userland-migrations/ecosystem", + "label": "components.navigation.learn.userland-migrations.links.ecosystem" + }, + "v20-to-v22": { + "link": "/learn/userland-migrations/v20-to-v22", + "label": "components.navigation.learn.userland-migrations.links.v20-to-v22" + }, + "v14-to-v16": { + "link": "/learn/userland-migrations/v14-to-v16", + "label": "components.navigation.learn.userland-migrations.links.v14-to-v16" } } }, diff --git a/apps/site/pages/en/learn/migrations/introduction.md b/apps/site/pages/en/learn/migrations/introduction.md deleted file mode 100644 index 40c45a25259f5..0000000000000 --- a/apps/site/pages/en/learn/migrations/introduction.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Userland Migrations -layout: learn -authors: JakobJingleheimer ---- - -# 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://www.codemod.com), 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`](https://github.com/orgs/nodejs/teams/userland-migrations) team. - -Official migrations are published under the `@nodejs` namespace within the [codemod registry](https://codemod.com/registry?framework=node.js). 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. - -A migration alters a project's source-code to apply a new design pattern, like: - -```console -cd path/to/your/project -npx codemod@latest @nodejs/correct-ts-specifiers -``` - -The cited migration transforms legacy typescript imports to standards-compliant specifiers like: - -```ts displayName="before" -import Foo from './foo'; -``` - -```ts displayName="after" -import type Foo from './foo/index.ts'; -``` diff --git a/apps/site/pages/en/learn/userland-migrations/ecosystem.md b/apps/site/pages/en/learn/userland-migrations/ecosystem.md new file mode 100644 index 0000000000000..07849396787e3 --- /dev/null +++ b/apps/site/pages/en/learn/userland-migrations/ecosystem.md @@ -0,0 +1,25 @@ +--- +title: Ecosystem to Node.js +layout: learn +authors: AugustinMauroy +--- + +# Ecosystem to Node.js + +Sometimes the ecosystem creates awesome tools or libraries for node.js, but a native alternative is present in Node.js. So, this page shows you codemod that handle this case. + +## `correct-ts-specifiers` + +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: + +```bash +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). + +## 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). diff --git a/apps/site/pages/en/learn/userland-migrations/introduction.md b/apps/site/pages/en/learn/userland-migrations/introduction.md new file mode 100644 index 0000000000000..a254ae6fbb835 --- /dev/null +++ b/apps/site/pages/en/learn/userland-migrations/introduction.md @@ -0,0 +1,74 @@ +--- +title: Userland Migrations +layout: learn +authors: JakobJingleheimer, AugustinMauroy +--- + +![Node.js Userland Migrations](https://raw.githubusercontent.com/nodejs/userland-migrations/main/.github/assets/Userland-Migration-Tagline.png) + +# 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. + + + +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 + +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. + +## How to use a Codemod + +To use a codemod, you can run the following command in your terminal: + +```bash displayName="npm" +npx codemod@next +``` + +```bash displayName="yarn" +yarn dlx codemod@next +``` + +```bash displayName="pnpm" +pnpx codemod@next +``` + +Replace `` with the name of the codemod you want to run. For example, if you want to run the `@nodejs/import-assertions-to-attributes` codemod on your project, you would run: + +```bash displayName="npm" +npx codemod@next @nodejs/import-assertions-to-attributes +``` + +```bash displayName="yarn" +yarn dlx codemod@next @nodejs/import-assertions-to-attributes +``` + +```bash displayName="pnpm" +pnpx codemod@next @nodejs/import-assertions-to-attributes +``` + +## Good Practices + +- **Run migrations in a separate branch**: If you are using a version control system like Git, it is a good practice to run migrations in a separate branch. This allows you to review the changes before merging them into your main branch. +- **Review changes**: After running a migration, review the changes made to your codebase. Ensure that the migration has not introduced any unintended side effects or issues. +- **Test your code**: After running a migration, it is important to test your code to ensure that everything is working as expected. Run your test suite and check for any errors or failures + +## Feedback + +If you have any feedback or suggestions for improvements, please open an issue on the [Node.js Userland Migrations repository](https://github.com/nodejs/userland-migrations/issues). + +## Follow the Userland Migrations Progression + +You can follow the progress of userland migrations on our [GitHub project board](https://github.com/orgs/nodejs/projects/13/views/1). + +This board tracks: + +- Codemod kind (deprecation, breaking change, ecosystem) +- Node.js version +- Status (backlog, todo, in progress, done, not planned) _If you want to contribute, please check the "todo" column_ diff --git a/apps/site/pages/en/learn/userland-migrations/v14-to-v16.md b/apps/site/pages/en/learn/userland-migrations/v14-to-v16.md new file mode 100644 index 0000000000000..773a0f4353d1f --- /dev/null +++ b/apps/site/pages/en/learn/userland-migrations/v14-to-v16.md @@ -0,0 +1,79 @@ +--- +title: Nodejs v14 to v16 +layout: learn +authors: AugustinMauroy +--- + +# Nodejs v14 to v16 + +This page provides a list of codemods to help you migrate your code from Node.js v14 to v16. + +## `create-require-from-path` + +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). + +```bash +npx codemod@latest @nodejs/create-require-from-path +``` + +Example: + +**Before:** + +```js +import { createRequireFromPath } from 'node:module'; + +// Using createRequireFromPath +const requireFromPath = createRequireFromPath('/path/to/module'); +const myModule = requireFromPath('./myModule.cjs'); +``` + +**After:** + +```js +import { createRequire } from 'node:module'; + +// Using createRequire with a specific path +const require = createRequire('/path/to/module'); +const myModule = require('./myModule.cjs'); +``` + +## `rmdir` + +In Node.js v16, the `fs.rmdir` function was deprecated in favor of `fs.rm` with the `{ recursive: true }` option. This codemod will help you replace the old `fs.rmdir` function with the new `fs.rm` function. + +so this codemod handle [DEP0147](https://nodejs.org/api/deprecations.html#DEP0147). + +```bash +npx codemod@latest @nodejs/rmdir +``` + +Example: + +**Before:** + +```js +// Using fs.rmdir with the recursive option +fs.rmdir(path, { recursive: true }, callback); + +// Using fs.rmdirSync with the recursive option +fs.rmdirSync(path, { recursive: true }); + +// Using fs.promises.rmdir with the recursive option +fs.promises.rmdir(path, { recursive: true }); +``` + +**After:** + +```js +// Using fs.rm with recursive and force options +fs.rm(path, { recursive: true, force: true }, callback); + +// Using fs.rmSync with recursive and force options +fs.rmSync(path, { recursive: true, force: true }); + +// Using fs.promises.rm with recursive and force options +fs.promises.rm(path, { recursive: true, force: true }); +``` diff --git a/apps/site/pages/en/learn/userland-migrations/v20-to-v22.md b/apps/site/pages/en/learn/userland-migrations/v20-to-v22.md new file mode 100644 index 0000000000000..d95d0b8d04edc --- /dev/null +++ b/apps/site/pages/en/learn/userland-migrations/v20-to-v22.md @@ -0,0 +1,29 @@ +--- +title: Nodejs v20 to v22 +layout: learn +authors: AugustinMauroy +--- + +# Nodejs v20 to v22 + +This page provides a list of codemods to help you migrate your code from Node.js v20 to v22. + +## `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. + +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. + +```bash +npx codemod@latest @nodejs/import-assertions-to-attributes +``` + +Example: + +```js +import jsonData from './data.json' assert { type: 'json' }; +// becomes +import jsonData from './data.json' with { type: 'json' }; +``` diff --git a/packages/i18n/src/locales/en.json b/packages/i18n/src/locales/en.json index cadcca42859f3..bb1cbe390e3ad 100644 --- a/packages/i18n/src/locales/en.json +++ b/packages/i18n/src/locales/en.json @@ -99,10 +99,13 @@ "acceptInputFromTheCommandLineInNodejs": "Accept input from the command line in Node.js" } }, - "migrations": { + "userland-migrations": { "links": { - "migrations": "Userland Migrations", - "introduction": "Introduction to Userland Migrations" + "userland-migrations": "Userland Migrations", + "introduction": "Introduction to Userland Migrations", + "ecosystem": "Ecosystem to Node.js", + "v20-to-v22": "Node.js v20 to v22", + "v14-to-v16": "Node.js v14 to v16" } }, "modules": {