From 24c1705da5e5d68a53fc75efb91379a3e30a71fd Mon Sep 17 00:00:00 2001 From: Adrian Estrada Date: Mon, 15 Jun 2026 15:50:30 -0500 Subject: [PATCH 1/2] feat: add Upgrading Node.js info page and navigation --- apps/site/mdx/components.mjs | 2 + apps/site/navigation.json | 4 + apps/site/pages/en/about/eol.mdx | 6 +- apps/site/pages/en/about/upgrading-nodejs.mdx | 77 +++++++++++++++++++ packages/i18n/src/locales/en.json | 3 +- pnpm-workspace.yaml | 1 + 6 files changed, 91 insertions(+), 2 deletions(-) create mode 100644 apps/site/pages/en/about/upgrading-nodejs.mdx diff --git a/apps/site/mdx/components.mjs b/apps/site/mdx/components.mjs index 46db7dc2afe11..56c6abf7c12fb 100644 --- a/apps/site/mdx/components.mjs +++ b/apps/site/mdx/components.mjs @@ -3,6 +3,7 @@ import AlertBox from '@node-core/ui-components/Common/AlertBox'; import BadgeGroup from '@node-core/ui-components/Common/BadgeGroup'; import Blockquote from '@node-core/ui-components/Common/Blockquote'; +import NodeSourceLogo from '@node-core/ui-components/Icons/PartnerLogos/NodeSource/Logo'; import MDXCodeTabs from '@node-core/ui-components/MDX/CodeTabs'; import { MDXTooltip, @@ -102,4 +103,5 @@ export default { Button, Link, LinkWithArrow, + NodeSourceLogo, }; diff --git a/apps/site/navigation.json b/apps/site/navigation.json index 65d0e9f69b295..e7d9c1f358f98 100644 --- a/apps/site/navigation.json +++ b/apps/site/navigation.json @@ -141,6 +141,10 @@ "eol": { "link": "/about/eol", "label": "components.navigation.about.links.eol" + }, + "upgradeAdvisor": { + "link": "/about/upgrading-nodejs", + "label": "components.navigation.about.links.upgradeAdvisor" } } }, diff --git a/apps/site/pages/en/about/eol.mdx b/apps/site/pages/en/about/eol.mdx index 7860f6ecd360c..dbea39c83306a 100644 --- a/apps/site/pages/en/about/eol.mdx +++ b/apps/site/pages/en/about/eol.mdx @@ -11,7 +11,7 @@ description: Understand Node.js End-of-Life, what it means for security, tooling Major versions of Node.js are released, patched, and designated End-Of-Life on a predictable schedule. As it's not feasible to maintain all release lines in perpetuity, after a planned maintenance period, a Node.js major release line will stop being maintained by the project.
- or @@ -42,3 +42,7 @@ Despite the obvious downsides of using EOL releases, in practice, organizations HeroDevs provides [Never-Ending Support (NES)](https://nodejs.org/esp/herodevs) for Node.js versions past their official maintenance phase. This includes security patches, compliance assistance, and technical support to help bridge the gap while you plan your upgrade strategy. Using EOL releases through commercial support should be viewed as a temporary solution—the goal should always be to upgrade to actively supported versions. + +## Need help upgrading? + +If you are planning an upgrade from an EOL version, you can utilize the [Upgrading Node.js](/about/upgrading-nodejs) page to get a free assessment of your application's readiness and a migration roadmap. diff --git a/apps/site/pages/en/about/upgrading-nodejs.mdx b/apps/site/pages/en/about/upgrading-nodejs.mdx new file mode 100644 index 0000000000000..2d9e35aef0942 --- /dev/null +++ b/apps/site/pages/en/about/upgrading-nodejs.mdx @@ -0,0 +1,77 @@ +--- +title: Upgrading Node.js +layout: about +description: Get a free assessment to upgrade your Node.js applications with confidence. +--- + +# Upgrading Node.js + +Keeping your Node.js applications up-to-date is crucial for security, performance, and accessing the latest features. However, migrating from legacy versions can be challenging due to breaking changes, deprecated APIs, and dependency conflicts. + +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. + +## Why Upgrade? + +- **Security**: Insight into vulnerabilities affecting your specific codebase. +- **Performance**: Leverage the latest V8 engine improvements and Node.js optimizations. +- **Support**: Ensure your applications are on supported release lines (LTS). + +## How to Upgrade + +Upgrading a Node.js application typically involves the following steps: + +1. **Assessment of Node.js versions, dependencies, and risk**: Identify outdated or supported versions and potential security risks in your environment. +2. **Review Changelogs & Plan**: Look for breaking changes and create a phased upgrade plan for supported LTS releases. +3. **Update Dependencies**: Ensure your third-party packages are compatible with the new Node.js version. +4. **Hands-on execution**: Refactor code to address deprecations and breaking changes. +5. **Run Tests**: Execute your test suite to identify any immediate regressions. +6. **Deploy**: Roll out the upgrade to your staging and production environments. + +Take the first step and download the latest Node.js version. + +
+ +
+ +## Risks Determining the Upgrade Complexity + + + While necessary, upgrades can introduce risks that need to be managed + carefully. + + +- **Breaking Changes**: APIs may have changed or been removed, causing runtime errors. +- **Dependency Incompatibility**: Critical libraries might not yet support the new Node.js version. +- **Silent Failures**: Subtle behavior changes in the runtime can lead to difficult-to-debug issues. + +## Ecosystem Support Programs + +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. + +The following service providers participate in the OpenJS Foundation's LTS Upgrade & Modernization program: + +### NodeSource + +
+ +
+ +[NodeSource](https://nodesource.com/products/nodejs-upgrade) provides upgrade assessment tools and expert-guided modernization services under the Foundation's framework. Their program offers a structured path to modernization: + +- **Scan Your App (Free)**: NodeSource's public "Upgrade Discovery CLI" tool scans your project's environment for dependencies, C++ addons, and static API usage. +- **AI-Powered Analysis (Free)**: Receive deep insights including executive scores for security and upgrade risk, identification of critical blockers, and a complete scan for deprecated APIs and vulnerabilities. +- **Custom Modernization Plan**: Access a tailored roadmap, specialized tools, and technical support from NodeSource experts to ensure a safe and efficient migration. + +
+ +
+ +The OpenJS Foundation's Ecosystem Support Programs connect the Node.js community with qualified service providers. If your organization is interested in becoming a program participant, [contact the Foundation](https://openjsf.org/). diff --git a/packages/i18n/src/locales/en.json b/packages/i18n/src/locales/en.json index 4fbbeb0c19b46..e7f409e42e92d 100644 --- a/packages/i18n/src/locales/en.json +++ b/packages/i18n/src/locales/en.json @@ -55,7 +55,8 @@ "releases": "Node.js Releases", "security": "Security Reporting", "partners": "Partners & Supporters", - "eol": "End-of-Life (EOL)" + "eol": "End-of-Life (EOL)", + "upgradeAdvisor": "Upgrading Node.js" } }, "getInvolved": { diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 2de78bf7999ac..7e79cb78b136c 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -9,6 +9,7 @@ allowBuilds: sharp: true unrs-resolver: true workerd: true + '@nodejs/doc-kit': true catalog: '@types/node': ^24.10.1 From d3a2e27b67e087a670103fb5f25c4689b58ebf9f Mon Sep 17 00:00:00 2001 From: Adrian Estrada Date: Mon, 15 Jun 2026 15:50:42 -0500 Subject: [PATCH 2/2] refactor: rewrite OSS section with Userland Migrations WG content --- apps/site/pages/en/about/upgrading-nodejs.mdx | 37 ++++++++----------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/apps/site/pages/en/about/upgrading-nodejs.mdx b/apps/site/pages/en/about/upgrading-nodejs.mdx index 2d9e35aef0942..788c2fbfca1c5 100644 --- a/apps/site/pages/en/about/upgrading-nodejs.mdx +++ b/apps/site/pages/en/about/upgrading-nodejs.mdx @@ -10,24 +10,30 @@ Keeping your Node.js applications up-to-date is crucial for security, performanc 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. -## Why Upgrade? +## Open Source Migration Resources + +### Why Upgrade? - **Security**: Insight into vulnerabilities affecting your specific codebase. - **Performance**: Leverage the latest V8 engine improvements and Node.js optimizations. - **Support**: Ensure your applications are on supported release lines (LTS). -## How to Upgrade - -Upgrading a Node.js application typically involves the following steps: +### How to Upgrade -1. **Assessment of Node.js versions, dependencies, and risk**: Identify outdated or supported versions and potential security risks in your environment. -2. **Review Changelogs & Plan**: Look for breaking changes and create a phased upgrade plan for supported LTS releases. +1. **Assessment**: Identify outdated versions, dependencies, and potential risks. +2. **Review & Plan**: Check changelogs for breaking changes and create a phased upgrade plan. 3. **Update Dependencies**: Ensure your third-party packages are compatible with the new Node.js version. -4. **Hands-on execution**: Refactor code to address deprecations and breaking changes. -5. **Run Tests**: Execute your test suite to identify any immediate regressions. -6. **Deploy**: Roll out the upgrade to your staging and production environments. +4. **Execute**: Refactor code to address deprecations and breaking changes. +5. **Test**: Run your test suite to catch regressions. +6. **Deploy**: Roll out the upgrade to staging and production. + +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: + +```bash +npx codemod @nodejs/ +``` -Take the first step and download the latest Node.js version. +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.
-## Risks Determining the Upgrade Complexity - - - While necessary, upgrades can introduce risks that need to be managed - carefully. - - -- **Breaking Changes**: APIs may have changed or been removed, causing runtime errors. -- **Dependency Incompatibility**: Critical libraries might not yet support the new Node.js version. -- **Silent Failures**: Subtle behavior changes in the runtime can lead to difficult-to-debug issues. - ## Ecosystem Support Programs 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.