Skip to content

Commit d3a2e27

Browse files
committed
refactor: rewrite OSS section with Userland Migrations WG content
1 parent 24c1705 commit d3a2e27

1 file changed

Lines changed: 16 additions & 21 deletions

File tree

apps/site/pages/en/about/upgrading-nodejs.mdx

Lines changed: 16 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -10,42 +10,37 @@ Keeping your Node.js applications up-to-date is crucial for security, performanc
1010

1111
Node.js itself is and always will be free, open source software. The guidance below is designed to help you plan and execute upgrades, whether you do it yourself or work with one of the service providers in our ecosystem.
1212

13-
## Why Upgrade?
13+
## Open Source Migration Resources
14+
15+
### Why Upgrade?
1416

1517
- **Security**: Insight into vulnerabilities affecting your specific codebase.
1618
- **Performance**: Leverage the latest V8 engine improvements and Node.js optimizations.
1719
- **Support**: Ensure your applications are on supported release lines (LTS).
1820

19-
## How to Upgrade
20-
21-
Upgrading a Node.js application typically involves the following steps:
21+
### How to Upgrade
2222

23-
1. **Assessment of Node.js versions, dependencies, and risk**: Identify outdated or supported versions and potential security risks in your environment.
24-
2. **Review Changelogs & Plan**: Look for breaking changes and create a phased upgrade plan for supported LTS releases.
23+
1. **Assessment**: Identify outdated versions, dependencies, and potential risks.
24+
2. **Review & Plan**: Check changelogs for breaking changes and create a phased upgrade plan.
2525
3. **Update Dependencies**: Ensure your third-party packages are compatible with the new Node.js version.
26-
4. **Hands-on execution**: Refactor code to address deprecations and breaking changes.
27-
5. **Run Tests**: Execute your test suite to identify any immediate regressions.
28-
6. **Deploy**: Roll out the upgrade to your staging and production environments.
26+
4. **Execute**: Refactor code to address deprecations and breaking changes.
27+
5. **Test**: Run your test suite to catch regressions.
28+
6. **Deploy**: Roll out the upgrade to staging and production.
29+
30+
Upgrades can introduce risks — breaking changes, dependency incompatibilities, and subtle runtime differences that are hard to debug. To help with Step 4, the [Node.js Userland Migrations Working Group](https://github.com/nodejs/userland-migrations) provides **codemods**, automated code transformations that handle specific breaking changes across your codebase:
31+
32+
```bash
33+
npx codemod @nodejs/<recipe>
34+
```
2935

30-
Take the first step and download the latest Node.js version.
36+
These community-maintained recipes are published in the [Codemod Registry](https://registry.codemod.com), letting you incrementally adopt fixes without a full rewrite. Contributions are welcome — author new recipes, review existing ones, or help shape the ecosystem's migration strategy.
3137

3238
<div className="my-8 flex w-full justify-center">
3339
<Button kind="primary" href="/download">
3440
<span>Download the latest LTS Node.js®</span>
3541
</Button>
3642
</div>
3743

38-
## Risks Determining the Upgrade Complexity
39-
40-
<AlertBox level="warning">
41-
While necessary, upgrades can introduce risks that need to be managed
42-
carefully.
43-
</AlertBox>
44-
45-
- **Breaking Changes**: APIs may have changed or been removed, causing runtime errors.
46-
- **Dependency Incompatibility**: Critical libraries might not yet support the new Node.js version.
47-
- **Silent Failures**: Subtle behavior changes in the runtime can lead to difficult-to-debug issues.
48-
4944
## Ecosystem Support Programs
5045

5146
The OpenJS Foundation has established an LTS Upgrade & Modernization framework to help organizations move safely off legacy and end-of-life (EOL) Node.js versions. As the nonprofit steward of Node.js, the Foundation defines the program standards, ensures alignment with the upstream project, and works with qualified service providers who deliver tools and technical support under this framework.

0 commit comments

Comments
 (0)