diff --git a/apps/site/layouts/Blog.tsx b/apps/site/layouts/Blog.tsx index c9d13d401aba8..aa389a952289b 100644 --- a/apps/site/layouts/Blog.tsx +++ b/apps/site/layouts/Blog.tsx @@ -63,6 +63,7 @@ const BlogLayout: FC = () => { 'announcements', 'release', 'vulnerability', + 'migrations', 'events', ])} /> diff --git a/apps/site/mdx/components.mjs b/apps/site/mdx/components.mjs index 400d79a8542ea..1f4a7e06e0a41 100644 --- a/apps/site/mdx/components.mjs +++ b/apps/site/mdx/components.mjs @@ -1,5 +1,6 @@ 'use strict'; +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 MDXCodeTabs from '@node-core/ui-components/MDX/CodeTabs'; @@ -54,6 +55,8 @@ export default { blockquote: Blockquote, pre: MDXCodeBox, img: MDXImage, + // Renders a CSS-enhanced Alert Box + AlertBox, // Renders MDX CodeTabs CodeTabs: MDXCodeTabs, // Renders Tooltips diff --git a/apps/site/navigation.json b/apps/site/navigation.json index 0514ce54fd689..5ea92432ebb6d 100644 --- a/apps/site/navigation.json +++ b/apps/site/navigation.json @@ -205,6 +205,10 @@ "securityBestPractices": { "link": "/learn/getting-started/security-best-practices", "label": "components.navigation.learn.gettingStarted.links.securityBestPractices" + }, + "userlandMigrations": { + "link": "/learn/getting-started/userland-migrations", + "label": "components.navigation.learn.gettingStarted.links.userlandMigrations" } } }, @@ -336,15 +340,6 @@ } } }, - "migrations": { - "label": "components.navigation.learn.migrations.links.migrations", - "items": { - "introduction": { - "link": "/learn/migrations/introduction", - "label": "components.navigation.learn.migrations.links.introduction" - } - } - }, "modules": { "label": "components.navigation.learn.modules.links.modules", "items": { @@ -419,6 +414,31 @@ "label": "components.navigation.learn.testRunner.links.collectingCodeCoverage" } } + }, + "userland-migrations": { + "label": "components.navigation.learn.userland-migrations.links.userland-migrations", + "items": { + "introduction": { + "link": "/learn/userland-migrations/introduction", + "label": "components.navigation.learn.userland-migrations.links.introduction" + }, + "ecosystem": { + "link": "/learn/userland-migrations/ecosystem", + "label": "components.navigation.learn.userland-migrations.links.ecosystem" + }, + "v22-to-v24": { + "link": "/learn/userland-migrations/v22-to-v24", + "label": "components.navigation.learn.userland-migrations.links.v22-to-v24" + }, + "v20-to-v22": { + "link": "/learn/userland-migrations/v20-to-v22", + "label": "components.navigation.learn.userland-migrations.links.v20-to-v22" + }, + "v14-to-v16": { + "link": "/learn/userland-migrations/v14-to-v16", + "label": "components.navigation.learn.userland-migrations.links.v14-to-v16" + } + } } } } diff --git a/apps/site/pages/en/blog/migrations/v12-to-v14.mdx b/apps/site/pages/en/blog/migrations/v12-to-v14.mdx new file mode 100644 index 0000000000000..05db40649ef16 --- /dev/null +++ b/apps/site/pages/en/blog/migrations/v12-to-v14.mdx @@ -0,0 +1,52 @@ +--- +date: '2025-10-28T00:00:00.000Z' +category: migrations +title: Node.js v12 to v14 +layout: blog-post +author: AugustinMauroy +--- + +# Node.js v12 to v14 + + + This article cover a part of the migration from Node.js v12 to v14. The + userland migrations team is working on more codemods to help you with the + migration. + + +This page provides a list of codemods to help you migrate your code from Node.js v12 to v14. + +## `util-print-to-console-log` + +This recipe transforms calls of various now-deprecated `node:util` log functions into the modern alternative, `console.log` and `console.error`: + +- [DEP0026](https://nodejs.org/api/deprecations.html#DEP0026): `util.print` → `console.log` +- [DEP0027](https://nodejs.org/api/deprecations.html#DEP0027): `util.puts` → `console.log` +- [DEP0028](https://nodejs.org/api/deprecations.html#DEP0028): `util.debug` → `console.error` +- [DEP0029](https://nodejs.org/api/deprecations.html#DEP0029): `util.error` → `console.error` + +The source code for this codemod can be found in the [util-print-to-console-log directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/util-print-to-console-log). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/util-print-to-console-log). + +```bash +npx codemod run @nodejs/create-require-from-path +``` + +### Example: + +```js displayName="Before" +const util = require('node:util'); + +util.print('Hello world'); +util.puts('Hello world'); +util.debug('Hello world'); +util.error('Hello world'); +``` + +```js displayName="After" +console.log('Hello world'); +console.log('Hello world'); +console.error('Hello world'); +console.error('Hello world'); +``` diff --git a/apps/site/pages/en/blog/migrations/v14-to-v16.mdx b/apps/site/pages/en/blog/migrations/v14-to-v16.mdx new file mode 100644 index 0000000000000..735055f57b901 --- /dev/null +++ b/apps/site/pages/en/blog/migrations/v14-to-v16.mdx @@ -0,0 +1,169 @@ +--- +date: '2025-10-28T00:01:00.000Z' +category: migrations +title: Node.js v14 to v16 +layout: blog-post +author: AugustinMauroy +--- + +# Node.js v14 to v16 + + + This article cover a part of the migration from Node.js v14 to v16. The + userland migrations team is working on more codemods to help you with the + migration. + + +This page provides a list of codemods to help you migrate your code from Node.js v14 to v16. + +## `create-require-from-path` + +Node.js v16 replaced the [`createRequireFromPath`](https://nodejs.org/api/module.html#module_module_createrequirefrompath) function, deprecated in [DEP0148](https://nodejs.org/api/deprecations.html#DEP0148), with the modern [`createRequire`](https://nodejs.org/api/module.html#module_module_createrequire) function. This codemod replaces calls of the deprecated function with the modern alternative mentioned. + +The source code for this codemod can be found in the [create-require-from-path directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/create-require-from-path). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/create-require-from-path). + +```bash +npx codemod run @nodejs/create-require-from-path +``` + +### Example: + +```js displayName="Before" +import { createRequireFromPath } from 'node:module'; + +const requireFromPath = createRequireFromPath('/path/to/module'); +const myModule = requireFromPath('./myModule.cjs'); +``` + +```js displayName="After" +import { createRequire } from 'node:module'; + +const require = createRequire('/path/to/module'); +const myModule = require('./myModule.cjs'); +``` + +## `process-main-module` + +The `process.mainModule` property was deprecated in favor of `require.main`. This codemod will help you replace the old `process.mainModule` usage with the new `require.main` usage. + +So the codemod handle [DEP0138](https://nodejs.org/api/deprecations.html#DEP0138). + +The source code for this codemod can be found in the [process-main-module directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/process-main-module). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/process-main-module). + +```bash +npx codemod run @nodejs/process-main-module +``` + +### Example: + +```js displayName="Before" +if (process.mainModule === 'mod.js') { + // cli thing +} else { + // module thing +} +``` + +```js displayName="After" +if (require.main === 'mod.js') { + // cli thing +} else { + // module thing +} +``` + +## `process-mainModule-to-require-main` + +The [`process.mainModule`](https://nodejs.org/api/process.html#process_process_mainmodule) property was deprecated ([DEP0144](https://nodejs.org/api/deprecations.html#DEP0144)) in favor of [`require.main`](https://nodejs.org/api/modules.html#modules_accessing_the_main_module). This codemod replaces calls of the deprecated property with the modern alternative mentioned. + +The source code for this codemod can be found in the [process-mainModule-to-require-main directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/process-main-module). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/process-mainModule-to-require-main). + +```bash +npx codemod run @nodejs/process-mainModule-to-require-main +``` + +### Example: + +```js displayName="Before" +if (process.mainModule) { + console.log('This script is the main module'); +} +``` + +```js displayName="After" +if (require.main === module) { + console.log('This script is the main module'); +} +``` + +## `rmdir` + +The `fs.rmdir` function was deprecated in favor of `fs.rm` with the `{ recursive: true }` option. This codemod will help you replace the old `fs.rmdir` function with the new `fs.rm` function. + +so this codemod handle [DEP0147](https://nodejs.org/api/deprecations.html#DEP0147). + +The source code for this codemod can be found in the [rmdir directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/rmdir). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/rmdir). + +```bash +npx codemod run @nodejs/rmdir +``` + +### Example: + +```js displayName="Before" +// Using fs.rmdir with the recursive option +fs.rmdir(path, { recursive: true }, callback); + +// Using fs.rmdirSync with the recursive option +fs.rmdirSync(path, { recursive: true }); + +// Using fs.promises.rmdir with the recursive option +fs.promises.rmdir(path, { recursive: true }); +``` + +```js displayName="After" +// Using fs.rm with recursive and force options +fs.rm(path, { recursive: true, force: true }, callback); + +// Using fs.rmSync with recursive and force options +fs.rmSync(path, { recursive: true, force: true }); + +// Using fs.promises.rm with recursive and force options +fs.promises.rm(path, { recursive: true, force: true }); +``` + +## `tmpDir-to-tmpdir` + +The `tmpDir` function was renamed to `tmpdir` in Node.js v16. This codemod will help you replace all instances of `tmpDir` with `tmpdir`. + +So the codemod handles [DEP0022](https://nodejs.org/docs/latest/api/deprecations.html#dep0022-ostmpdir). + +The source code for this codemod can be found in the [tmpdir-to-tmpdir directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/tmpdir-to-tmpdir). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/tmpDir-to-tmpdir). + +```bash +npx codemod run @nodejs/tmpDir-to-tmpdir +``` + +### Example: + +```js displayName="Before" +import { tmpDir } from 'node:os'; + +const foo = tmpDir(); +``` + +```js displayName="After" +import { tmpdir } from 'node:os'; + +const foo = tmpdir(); +``` diff --git a/apps/site/pages/en/blog/migrations/v20-to-v22.mdx b/apps/site/pages/en/blog/migrations/v20-to-v22.mdx new file mode 100644 index 0000000000000..533eee5255b7c --- /dev/null +++ b/apps/site/pages/en/blog/migrations/v20-to-v22.mdx @@ -0,0 +1,43 @@ +--- +date: '2025-10-28T00:02:00.000Z' +category: migrations +title: Node.js v20 to v22 +layout: blog-post +author: AugustinMauroy +--- + +# Node.js v20 to v22 + + + This article cover a part of the migration from Node.js v20 to v22. The + userland migrations team is working on more codemods to help you with the + migration. + + +This page provides a list of codemods to help you migrate your code from Node.js v20 to v22. + +## `import-assertions-to-attributes` + +During the process of TC39 standardization, the `import assert` feature was introduced to allow importing [JSON modules](https://tc39.es/proposal-json-modules/), but during the during the transition to stage 4, the `assert` keyword was replaced with an `with` attribute on the `import` statement. + +So in [node.js v22](https://nodejs.org/fr/blog/release/v22.0.0#other-notable-changes), the `import assert` feature was removed and the `with` attribute is required instead. + +Also note that the `with` keyword as been introduce in [node.js v18.20](https://nodejs.org/fr/blog/release/v18.20.0#added-support-for-import-attributes) but it was not mandatory until v22. + +The source code for this codemod can be found in the [import-assertions-to-attributes directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/import-assertions-to-attributes). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/import-assertions-to-attributes). + +```bash +npx codemod run @nodejs/import-assertions-to-attributes +``` + +### Example: + +```js displayName="Before" +import jsonData from './data.json' assert { type: 'json' }; +``` + +```js displayName="After" +import jsonData from './data.json' with { type: 'json' }; +``` diff --git a/apps/site/pages/en/blog/migrations/v22-to-v24.mdx b/apps/site/pages/en/blog/migrations/v22-to-v24.mdx new file mode 100644 index 0000000000000..c8f09328b261d --- /dev/null +++ b/apps/site/pages/en/blog/migrations/v22-to-v24.mdx @@ -0,0 +1,238 @@ +--- +date: '2025-10-28T00:03:00.000Z' +category: migrations +title: Node.js v22 to v24 +layout: blog-post +author: AugustinMauroy +--- + +# Node.js v22 to v24 + + + This article cover a part of the migration from Node.js v22 to v24. The + userland migrations team is working on more codemods to help you with the + migration. + +Missing codemods will be added over time. If you have specific needs. + + + Read this issue to learn where we are in the process. And how to manually migrate your code. + + + +With the release of [Node.js 24.11.0](https://nodejs.org/blog/release/v24.11.0), the Node.js 24 release line has entered Long-Term Support (LTS) and will continue to receive updates through to the end of April 2028. + +If you are migrating from Node.js 22 LTS, the following summarizes the breaking changes that came in [Node.js 23.0.0](https://nodejs.org/blog/release/v23.0.0) and [Node.js 24.0.0](https://nodejs.org/blog/release/v24.0.0). + +### Platform support + +Node.js no longer provides [pre-built binaries](https://nodejs.org/en/download) for: + +- 32-bit Windows (x86) as of Node.js 23.0.0. +- 32-bit Linux on armv7 as of Node.js 24.0.0. + +Pre-built binaries for macOS now require a minimum of macOS 13.5. + +Pre-built binaries for Linux on arm64, ppc64le, s390x and x64 continue to be compatible with glibc 2.28 and above (no change from Node.js 22). + +Please refer to [additional notes if you are building Node.js from source](#building-nodejs-from-source). + +### Breaking changes + +### OpenSSL 3.5 + +Pre-built binaries of Node.js 24 LTS, or builds using the default build configuration options, include OpenSSL 3.5. Node.js 24 LTS uses the default security level from OpenSSL 3.5 of `2`, which means that: + +- RSA, DSA and DH keys shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. +- Any cipher suite using RC4 is also prohibited. + +If you rely on older keys or weak ciphers, test your workloads against Node.js 24 builds (or adjust key/cipher choices) before upgrading. + +### Other behavioral changes and argument validation + +The release includes a number of behavior and validation changes (stricter `fetch()` compliance, AbortSignal validation, stream/pipe errors now throwing, changes to Buffer behavior, path handling fixes on Windows, test runner defaults, and more). See the full list below. + +### C/C++ addons + +Addons linking against V8 APIs may need updates for V8 13.6; C++20 support may be required where previously C++17 was used. Where possible, prefer NODE-API to reduce rebuild churn. + +### Building Node.js from source + +If you are building Node.js from source, you may need to update your compiler toolchain: + +- For AIX and Linux platforms, the minimum supported version of [gcc](https://gcc.gnu.org/) is 12.2. +- For macOS the minimum supported version of [Xcode](https://developer.apple.com/xcode/) is 16.1. + +Node.js' `configure` script will warn if you attempt to build Node.js with a compiler toolchain that does not meet the minimum supported version but will not actively prevent you from trying. + +## Available Codemods + +Some breaking changes or End of Life deprecations in Node.js 23 and 24 have associated codemods to help you update your codebase. Below is a list of the available codemods for this migration: + +### `fs-access-mode-constants` + +In Node.js 24, the `fs` module introduced a runtime deprecation for `F_OK`, `R_OK`, `W_OK`, and `X_OK` getters exposed directly on `node:fs`. Get them from `fs.constants` or `fs.promises.constants` instead. + +This codemod handles [DEP0176](https://nodejs.org/api/deprecations.html#DEP0176). + +The source code for this codemod can be found in the [fs-access-mode-constants directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/fs-access-mode-constants). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/fs-access-mode-constants). + +```bash +npx codemod run @nodejs/fs-access-mode-constants +``` + +#### Example: + +```js displayName="Before" +const fs = require('node:fs'); + +fs.access('/path/to/file', fs.F_OK, callback); +fs.access('/path/to/file', fs.R_OK | fs.W_OK, callback); +``` + +```js displayName="After" +const fs = require('node:fs'); + +fs.access('/path/to/file', fs.constants.F_OK, callback); +fs.access('/path/to/file', fs.constants.R_OK | fs.constants.W_OK, callback); +``` + +### `util-log-to-console-log` + +In Node.js v23, the `util.log` function was deprecated in favor of using `console.log` directly. Because it's an unmaintained legacy API that was exposed to user land by accident + +So this codemod handle [DEP0059](https://nodejs.org/api/deprecations.html#DEP0059). + +```bash +npx codemod run @nodejs/util-log-to-console-log +``` + +### Example: + +```js displayName="Before" +const util = require('node:util'); + +util.log('Hello world'); +``` + +```js displayName="After" +console.log(new Date().toLocaleString(), 'Hello world'); +``` + +### `zlib-bytesRead-to-bytesWritten` + +The [`zlib.bytesRead`](https://nodejs.org/api/zlib.html#zlib_bytesread) property was deprecated ([DEP0108](https://nodejs.org/api/deprecations.html#DEP0108)) in favor of [`zlib.bytesWritten`](https://nodejs.org/api/zlib.html#zlib_byteswritten). This codemod replaces `zlib.bytesRead` with `zlib.bytesWritten` for consistent stream property naming. It handles both CommonJS and ESM imports. + +The source code for this codemod can be found in the [zlib-bytesRead-to-bytesWritten directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/zlib-bytesread-to-byteswritten). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/zlib-bytesread-to-byteswritten). + +```bash +npx codemod run @nodejs/zlib-bytesread-to-byteswritten +``` + +#### Example: + +```js displayName="Before" +const zlib = require('node:zlib'); +const gzip = zlib.createGzip(); +gzip.on('end', () => { + console.log('Bytes processed:', gzip.bytesRead); +}); +``` + +```js displayName="After" +const zlib = require('node:zlib'); +const gzip = zlib.createGzip(); +gzip.on('end', () => { + console.log('Bytes processed:', gzip.bytesWritten); +}); +``` + +### `fs-truncate-to-ftruncate` + +The [`fs.truncate`](https://nodejs.org/api/fs.html#fs_fs_truncate_path_len_callback) function was deprecated ([DEP0081](https://nodejs.org/api/deprecations.html#DEP0081)) when used with a file descriptor. Use [`fs.ftruncate`](https://nodejs.org/api/fs.html#fs_fs_ftruncate_fd_len_callback) instead. + +The source code for this codemod can be found in the [fs-truncate-fd-deprecation directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/fs-truncate-fd-deprecation). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/fs-truncate-to-ftruncate). + +```bash +npx codemod run @nodejs/fs-truncate-to-ftruncate +``` + +#### Example: + +```js displayName="Before" +const { truncate, open, close } = require('node:fs'); + +open('file.txt', 'w', (err, fd) => { + if (err) throw err; + truncate(fd, 10, err => { + if (err) throw err; + close(fd, () => {}); + }); +}); +``` + +```js displayName="After" +const { ftruncate, open, close } = require('node:fs'); + +open('file.txt', 'w', (err, fd) => { + if (err) throw err; + ftruncate(fd, 10, err => { + if (err) throw err; + close(fd, () => {}); + }); +}); +``` + +### `crypto-rsa-pss-update` + +Codemod to handle Node.js crypto deprecation [DEP0154](https://nodejs.org/docs/latest/api/deprecations.html#DEP0154) by transforming deprecated RSA-PSS key generation options. + +The source code for this codemod can be found in the [crypto-rsa-pss-update directory](https://github.com/nodejs/userland-migrations/tree/main/recipes/crypto-rsa-pss-update). + +You can find this codemod in the [Codemod Registry](https://app.codemod.com/registry/@nodejs/crypto-rsa-pss-update). + +```bash +npx codemod run @nodejs/crypto-rsa-pss-update +``` + +#### Example: + +```js displayName="Before" +const crypto = require('node:crypto'); + +crypto.generateKeyPair( + 'rsa-pss', + { + modulusLength: 2048, + hash: 'sha256', + mgf1Hash: 'sha1', + saltLength: 32, + }, + (err, publicKey, privateKey) => { + // callback + } +); +``` + +```js displayName="After" +const crypto = require('crypto'); + +crypto.generateKeyPair( + 'rsa-pss', + { + modulusLength: 2048, + hashAlgorithm: 'sha256', + mgf1HashAlgorithm: 'sha1', + saltLength: 32, + }, + (err, publicKey, privateKey) => { + // callback + } +); +``` diff --git a/apps/site/pages/en/learn/getting-started/userland-migrations.md b/apps/site/pages/en/learn/getting-started/userland-migrations.md new file mode 100644 index 0000000000000..92e19b565b885 --- /dev/null +++ b/apps/site/pages/en/learn/getting-started/userland-migrations.md @@ -0,0 +1,64 @@ +--- +title: Userland Migrations +layout: learn +authors: JakobJingleheimer, AugustinMauroy +--- + +![Node.js Userland Migrations](https://raw.githubusercontent.com/nodejs/userland-migrations/8fd9c141a118c4b64cc37eed8e663005cbc819ac/.github/assets/Userland-Migration-Tagline.png) + +# Userland Migrations + +Node.js offers migrations for "userland" code (anything outside the node executable) to help adopt new features and handle breaking changes. These are built in collaboration with [Codemod](https://codemod.com), a platform focused on making it easy to build, share, and run codemods. + +Official migrations are published under the `@nodejs` scope within the [Codemod registry](https://codemod.link/nodejs-official). These have been reviewed and/or authored by Node.js members. + +## Goal + +The Node.js Userland Migrations team seeks to help developers migrate their codebases to the latest Node.js versions, making it easier to handle deprecations, new features, and breaking changes. + +## How to use a codemod + +To use a codemod, you can run the following command in your terminal: + +```bash +npx codemod +``` + +Replace `` with the name of the codemod you want to run. For example, if you want to run the `@nodejs/import-assertions-to-attributes` codemod on your project, you would run: + +```bash +npx codemod @nodejs/import-assertions-to-attributes +``` + +## Good Practices + +- **Run migrations in a separate branch**: If you are using a version control system like Git, it is a good practice to run migrations in a separate branch. This allows you to review the changes before merging them into your main branch. +- **Review changes**: After running a migration, review the changes made to your codebase. Ensure that the migration has not introduced any unintended side effects or issues. +- **Test your code**: After running a migration, it is important to test your code to ensure that everything is working as expected. Run your test suite and check for any errors or failures +- **Format and or lint your code**: After running a migration, it is a good practice to format and lint your code. This ensures that your code follows the project's coding standards and is easier to read and maintain. + +## Understanding Codemods Registry + +The [Codemod registry](https://codemod.link/nodejs-official) provides a list of available codemods for Node.js. Some codemods may not be included in the following resources but are still available because they are not related to a specific migration to a Node.js version. Since we only list codemods for EoL deprecations, you may need to explore the registry for other codemods that could be useful for your migrations. + +> Please note that if you are logged into the Codemod platform, you can like these posts. This helps us to see what users find valuable. + +## Feedback + +If you have any feedback or suggestions for improvements, please open a discussion on the [Node.js Userland Migrations repository](https://github.com/nodejs/userland-migrations/discussions). + +## Follow the Userland Migrations Progression + +You can follow the progress of userland migrations on our [GitHub project board](https://github.com/orgs/nodejs/projects/13/views/1). + +This board tracks: + +- Codemod kind (deprecation, breaking change, ecosystem) +- Node.js version +- Status (backlog, todo, in progress, done, not planned) _If you want to contribute, please check the "todo" column_ + +## Migrations guides + +You can find all migrations guide on the [migration guides section](/blog/migrations). + +Please also note that migration guides for major-major releases only contain end-of-life [deprecations](https://nodejs.org/docs/latest/api/deprecations.html) and breaking changes. diff --git a/apps/site/pages/en/learn/migrations/introduction.md b/apps/site/pages/en/learn/migrations/introduction.md deleted file mode 100644 index 40c45a25259f5..0000000000000 --- a/apps/site/pages/en/learn/migrations/introduction.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Userland Migrations -layout: learn -authors: JakobJingleheimer ---- - -# Userland Migrations - -Node.js provides migrations for "userland" (what you write vs node's own) source-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 [`nodejs/userland-migrations`](https://github.com/nodejs/userland-migrations) repository and are overseen by the [`@nodejs/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 members. 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'; -``` diff --git a/packages/i18n/src/locales/en.json b/packages/i18n/src/locales/en.json index 653bd8f5e775c..fecfca49e2da4 100644 --- a/packages/i18n/src/locales/en.json +++ b/packages/i18n/src/locales/en.json @@ -48,7 +48,8 @@ "profiling": "Profiling Node.js Applications", "fetch": "Fetching data with Node.js", "websocket": "WebSocket client with Node.js", - "securityBestPractices": "Security Best Practices" + "securityBestPractices": "Security Best Practices", + "userlandMigrations": "Introduction to Userland Migrations" } }, "typescript": { @@ -98,12 +99,6 @@ "acceptInputFromTheCommandLineInNodejs": "Accept input from the command line in Node.js" } }, - "migrations": { - "links": { - "migrations": "Userland Migrations", - "introduction": "Introduction to Userland Migrations" - } - }, "modules": { "links": { "modules": "Modules", @@ -305,7 +300,7 @@ }, "blog": { "blogHeader": { - "subtitle": "The latest Node.js news, case studies, tutorials, and resources.", + "subtitle": "The latest Node.js news, migrations guides and events summaries", "rssLink": "RSS feed" } } @@ -336,6 +331,7 @@ "video": "Video", "weekly": "Weekly Updates", "wg": "Working Groups", + "migrations": "Migrations Guides", "events": "Events" } },