Skip to content

feat(learn/userland-migrations): add intro #7764

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
May 23, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions apps/site/navigation.json
Original file line number Diff line number Diff line change
@@ -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": {
28 changes: 28 additions & 0 deletions apps/site/pages/en/learn/migrations/introduction.md
Original file line number Diff line number Diff line change
@@ -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';
```
6 changes: 6 additions & 0 deletions packages/i18n/locales/en.json
Original file line number Diff line number Diff line change
@@ -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",