2025 Year in Review

2025 was a year of Node.js ecosystem transition toward proactive and automated maintenance for user code: The "Userland Migration" initiative took the project in a fundamental strategic shift, moving from a simple runtime updates to an active partner in transforming its users' codebases. The initiative's goal is to reduce the technical debt accumulated within one of the most expansive ecosystems in contemporary software engineering. Here we'll review the genesis, execution, and impact; we'll see it become evident that automation isn't merely a nice-to-have, but critical infrastructure for JavaScript's sustainability.

Dublin Collab Summit (where it started)

The concept of "Userland Migrations" started in 7–8 November 2024, during the "Dublin Collab Summit" in the Baseline Community Center. The discussions in Dublin highlighted a persistent friction: the difficulty for the community to adopt new features and navigate breaking changes. In particular, the ESM (ECMAScript Modules) adoption remained a major point of confusion, with some users not knowing precisely whether their production code was actually executed as ESM or CJS (authored as ESM, but transpiled by third-party tools like Next.js to CJS).

The numbers were clear, and anecdotal examples highlighted these painpoints. Documentation was not going to solve this problem any time soon. The brainstorming sessions explored novel solutions (opt-in telemetry, built-in transformation, et cetera), but the simplest and most popular quickly rose to the top, and was one that existed in the wild: codemod.

The first migration launched

On 16 May 16 2025, the initiative reached its first milestone with the first migration released: @nodejs/correct-ts-specifiers. This tool was specifically designed to resolve a longstanding technical tension between the TypeScript compiler (tsc) and the ESM specification. While TypeScript historically encouraged imports without extensions or mismatched extensions, ESM (and thus Node.js) requires file extensions to be present, true, and accurate.

The technical sophistication of this first codemod immediately established a high quality standard for the initiative. Unlike text search and replace tools, @nodejs/correct-ts-specifiers integrates file existence verification logic checking against the file system before applying the modification. In case of ambiguity, for example, if two files /tmp/foo.js and /tmp/foo.ts coexist, the migration logs and skips the transformation for that specific specifier, and proceeds through the rest of the codebase. It covers a wide breadth of pathing cases (including tsconfig "paths" if combined with a loader like @nodejs-loaders/alias).

This showed that Userland Migrations had the capability to tackle the complex interoperability problems encountered by the TypeScript community, which represents a predominant share of modern Node.js users.

From 0.0.1 to 1.0.0

After much collaboration with the Codemod team, Codemod CLI v1 launched in July 2025, and with it much of Userland Migrations’ technical setup significantly changed. This transition to version 1 wasn't a simple maintenance update, but a game-changer—a complete overhaul providing an all-in-one toolkit for enterprise-scale code refactoring. One of the major contributions of this version was the introduction of first-class workflows, allowing composition, validation, and execution of complex transformation sequences within a single tool.

The most striking innovation of v1 lies in its architecture. In particular:

• Testing: previously quite painful (and actually a bit dangerous: it previously modified test fixtures, and those changes were easy to commit by accident, completely invalidating the test). Now, it has a straightforward and before & after.

• It also greatly reduced the barrier to write; now we even have junior software engineers authoring high-quality migrations. The main barrier is knowledge of what before and after need to look like.

• Parallel execution has multiplied its efficiency on massive monorepos, while offering complete resumability. This functionality allows pausing a migration for manual inspection or following a system interruption, also ensuring successive steps of a multi-file migration remain consistent with each other.

Support for multiple workflow types has also expanded the tool's scope. The CLI v1 natively handles shell commands for script automation, but most importantly, it introduces codemods based on ast-grep (via JSSG and YAML). This abstract syntax tree (AST) approach enables much more precise transformations than string manipulations, as it understands the logical structure of the code.

Codemod CLI feature comparison

Feature	Version 0 (Experimental)	Version 1 (Production)
Workflow Management	Basic, manual	Composable, schema-validated
Execution	Sequential	Parallel and resumable
AST Engines	Limited	ast-grep (JSSG/YAML) native
Environment	Server dependencies	Self-hostable and portable
Project Structure	Ad-hoc	Standardised with metadata and tests

First migration with Codemod v1

The power of this new infrastructure was quickly put into use just a month later, with the launch of @nodejs/import-assertions-to-attributes. This migration was a technical necessity for users upgrading to Node.js 22.0.0 (in which import assertions was dropped and replaced by the now-standardised API).

The importance of this migration lies in its ability to maintain operational continuity for projects using JSON modules, which otherwise would have fully broken:

- import data from "./data.json" assert { type: "json" }
+ import data from "./data.json" with   { type: "json" }

But don't be fooled by the simplicity of this example: There are many permutations well beyond what is shown there (e.g. "type" is not the only attribute) which precludes a simple find+replace in many cases.

Partnership between Codemod and OpenJS Foundation

September 2025 marked a major institutional milestone with the formalization of a partnership between Codemod (the organization) and the OpenJS Foundation. This aims to sustain the Node.js ecosystem by industrializing the application update process. The stakes are high: maintaining the security and performance of enterprise systems depends on their ability to stay on supported runtime versions, a task often hindered by the complexity of manual migrations.

The partnership rests on three fundamental pillars:

• Simplifying major version migrations of Node.js through automated tools and specific guides.
• Promoting development best-practices by using codemods to inject more secure and performant code patterns during updates.
• Strengthening ecosystem sustainability by enabling small teams as well as large organizations to maintain their infrastructures up-to-date with minimal effort.

This collaboration bolsters Userland Migrations by bringing technological expertise of an organization specializing in code transformation and the support of the foundation hosting Node.js. For the OpenJS Foundation, this is a direct investment in the long-term health of its projects, recognizing that a runtime's viability depends not only on its features, but also on the ease with which its users can evolve. The partnership also signals to the market that Node.js is becoming an "enterprise-ready" platform across the entire value chain, from execution to maintenance.

Enter Migration Guides

Userland Migrations began a new phase of communicating with users in October 2025 with the creation of a dedicated migration portal (https://nodejs.org/en/blog/migrations). For the first time, Node.js centralised all its transition resources, ranging from conceptual explanations to practical codemod execution instructions. This is not just a repository of links; it's a hub explaining the rationale behind each breaking change.

Integrating these guides directly into the official blog and Node.js Learn section solved one of the problems raised at the Dublin summit: information fragmentation. By linking each blog entry about a new version to a corresponding migration guide, the project ensures that developers immediately have the necessary tools to take action. These guides emphasise real use-cases and provide "before/after" examples that facilitate understanding of the transformations performed by automated tools.

The documentation has also been enriched with sections on monorepo management and using package runners like npx to execute codemods without global installation, reflecting modern development practices. This holistic approach to documentation reduces developers' cognitive load, transforming software maintenance from a dreaded chore into a standardised and exhaustively documented procedure.

2025 Retrospection and adoption

At the end of 2025, usage statistics atest the initiative's success. With 26 official migrations published covering a spectrum from TypeScript fixes to core network transformations, the nodejs/userland-migrations repository is becoming an essential resource with steady adoption:

Total	2025 Performance Metric	Significance
26	Migrations published	Diversity of technical offerings
870	Unique users (since June)	Developer base penetration
941	Migrations run (since June)	Engagement and usage repeatability

Usage charted over time curves sharply up.

Analysis of the most popular migrations shows strong demand for handling historical deprecations. Tools like @nodejs/process-assert-to-node-assert and @nodejs/util-extend-to-object-assign demonstrate the community's desire to clean up legacy code to conform to modern APIs and standards. This trend indicates that migrations serve not only for major version adoption, but also for continuous improvement of code quality within the ecosystem.

2026 Roadmap and strategic vision

The 2026 horizon promises to be a period of acceleration and consolidation. The goal of reaching 5,000 unique users reflects an ambition to move from a niche project to an industry standard. The technical roadmap is already laid out with major projects.

Major Migration: Node.js v22 to v24

The main project for early 2026 is the @nodejs/v22-to-v24 migration bundle, tracked via issue #239. This bundle is designed to be a mega-migration, orchestrating dozens of individual transformations corresponding to deprecations introduced in Node.js 24. Analysis of priority tasks reveals exhaustive runtime coverage:

• Resource Management (fs): Replacement of access mode constants fs.F_OK, fs.R_OK, etc., with the new fs-access-mode-constants standards.
• Utility Cleanup (util): A massive transformation is planned for helpers util.isBoolean, util.isNull, and other deprecated type-checking methods, in favor of native JavaScript operators or more robust solutions.
• Timer Optimization: Update of internal timer management methods such as timers._unrefActive() to standardised public APIs.
• Network Protocols: Handling HTTP/2 priority signaling deprecation and modernization of repl (REPL) classes that now require using the new keyword during instantiation.

This grouped migration represents a qualitative leap. Instead of forcing developers to run 20 small tools, Node.js will offer a single command capable of scanning an entire project and making it compatible with version 24 in one pass, while managing dependencies between transformations.

The rise of type stripping and node:test runner

The initiative also plans to facilitate adoption of Node.js's flagship new features. Native "type stripping" requires specific migrations to help users adapt their code to Node.js's stripping constraints (migration(s) tracked in #267). These tools will be essential to simplify "zero-config" TypeScript adoption by the widest audience.

Another battlefront for 2026 is migration to the native node:test test runner. Developers increasingly seek to reduce their dependencies and benefit from the integrated runner's speed. Migrations under development (jest-to-node-test, tape-to-node-test) aim to ease or eliminate the the pain switching away from other runners (such as migrating harness symantics and mocking APIs).

Governance and community influence

Userland Migrations will integrate more deeply into Node.js project, including specific questions in the "Next-10" survey (issue #353) will help quantify the tools' real impact on developer productivity and adjust future investments based on needs expressed by the community. This data-driven approach ensures that foundation resources are allocated to transformations generating the most added value for end users.

Technical and cultural impact

The deployment of migrations in 2025 caused a subtle but profound cultural shift. By offloading the transformation of user code, Node.js raised the bar on stability—no longer the absence of change (which leads to stagnation), but the ability to change safely and easily. This philosophy drastically reduces the total cost of ownership (TCO) of Node.js applications in enterprises.

From a technical standpoint, the shift to AST-based transformations via ast-grep achieved a level of reliability that migration scripts of old didn't have. The ability to analyze code's logical structure enables handling complex cases such as variable scope, asynchronism, and types, without risking source code corruption. The initiative also fostered the emergence of a new contributor profile: the "maintainer-transformer", capable of writing not only features, but also associated migration rules.

The partnership with Codemod also introduced "migration campaign" concepts within monorepos. For organizations managing hundreds of microservices, the ability to orchestrate a Node.js update centrally, track automatically generated pull request progress, and validate changes at scale radically changes maintenance dynamics. This is the era of agent-assisted software maintenance, where human expertise is concentrated on validation rather than repetitive execution.

Thanks

The success of this first full year of Userland Migrations would not have been possible without collective effort. The community's gratitude goes first to individual contributors who spent hours dissecting syntax trees to create robust and reliable codemods. Their work, often invisible but crucial, is the engine of this transformation.

Special thanks are due to the Codemod team. Their platform, responsiveness to Node.js's specific needs, and vision of automated software maintenance have been indispensable catalysts for this success. The close collaboration between Codemod engineers and OpenJS Foundation members demonstrated that a public-private partnership model can work at the heart of open source for everyone's benefit.

Finally, thanks to users—independent developers, startups, and large enterprises—who dared to trust these tools from their earliest versions. Their feedback, bug reports, and improvement suggestions helped refine the technical infrastructure we know today. The Userland Migration initiative is, in essence, a community project whose value increases with each additional user.

Postscript

For those who wish to join the adventure or simply update their projects, the following resources are continuously updated:

• Learning Documentation: https://nodejs.org/en/learn/getting-started/userland-migrations
• Migration Guides Hub: https://nodejs.org/en/blog/migrations
• Contribution Repository: https://github.com/nodejs/userland-migrations

The future of Node.js is automated, secure, and focused on technical excellence. In 2026, the initiative will continue to push the boundaries of what's possible in large-scale software maintenance.

---

By: @AugustinMauroy, @JakobJingleheimer