diff --git a/apps/site/navigation.json b/apps/site/navigation.json index f18d7fb9a25af..f3cfb8cd9fa7c 100644 --- a/apps/site/navigation.json +++ b/apps/site/navigation.json @@ -332,6 +332,15 @@ } } }, + "migrations": { + "label": "components.navigation.learn.migrations.links.migrations", + "items": { + "introduction": { + "link": "/learn/migrations/introduction", + "label": "components.navigation.learn.migrations.links.introduction" + } + } + }, "modules": { "label": "components.navigation.learn.modules.links.modules", "items": { diff --git a/apps/site/pages/en/learn/migrations/introduction.md b/apps/site/pages/en/learn/migrations/introduction.md new file mode 100644 index 0000000000000..40c45a25259f5 --- /dev/null +++ b/apps/site/pages/en/learn/migrations/introduction.md @@ -0,0 +1,28 @@ +--- +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/packages/i18n/locales/en.json b/packages/i18n/locales/en.json index 156804a86cf2e..aa91e44a3ad9e 100644 --- a/packages/i18n/locales/en.json +++ b/packages/i18n/locales/en.json @@ -94,6 +94,12 @@ "acceptInputFromTheCommandLineInNodejs": "Accept input from the command line in Node.js" } }, + "migrations": { + "links": { + "migrations": "Userland Migrations", + "introduction": "Introduction to Userland Migrations" + } + }, "modules": { "links": { "modules": "Modules",