You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: apps/site/pages/en/about/upgrading-nodejs.mdx
+16-21Lines changed: 16 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,42 +10,37 @@ Keeping your Node.js applications up-to-date is crucial for security, performanc
10
10
11
11
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.
12
12
13
-
## Why Upgrade?
13
+
## Open Source Migration Resources
14
+
15
+
### Why Upgrade?
14
16
15
17
-**Security**: Insight into vulnerabilities affecting your specific codebase.
16
18
-**Performance**: Leverage the latest V8 engine improvements and Node.js optimizations.
17
19
-**Support**: Ensure your applications are on supported release lines (LTS).
18
20
19
-
## How to Upgrade
20
-
21
-
Upgrading a Node.js application typically involves the following steps:
21
+
### How to Upgrade
22
22
23
-
1.**Assessment of Node.js versions, dependencies, and risk**: Identify outdated or supported versionsand 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.
25
25
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
+
```
29
35
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.
31
37
32
38
<divclassName="my-8 flex w-full justify-center">
33
39
<Buttonkind="primary"href="/download">
34
40
<span>Download the latest LTS Node.js®</span>
35
41
</Button>
36
42
</div>
37
43
38
-
## Risks Determining the Upgrade Complexity
39
-
40
-
<AlertBoxlevel="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
-
49
44
## Ecosystem Support Programs
50
45
51
46
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