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
27 changes: 27 additions & 0 deletions apps/site/pages/en/learn/migrations/introduction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
---
title: Userland Migrations
layout: learn
authors: JakobJingleheimer
---

# Userland Migrations

Node.js provide migrations for "userland" 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 [`github://nodejs/userland-migrations`](https://github.com/nodejs/userland-migrations) repository and are overseen by the [`@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 collaborators. 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';
```
Loading