Skip to content

feat: support Node.js 24 in the builder and unenv-preset - #500

Draft
jose-filho-azion wants to merge 11 commits into
mainfrom
feat/node-24-support
Draft

jose-filho-azion wants to merge 11 commits into
mainfrom
feat/node-24-support

Conversation

@jose-filho-azion

Copy link
Copy Markdown
Contributor

Description

Adds Node.js 24 support to @aziontech/builder and @aziontech/unenv-preset, for both building apps and running them (azion dev and the Azion runtime). Node.js 22 stays supported and is now the minimum version.

The difference between 22 and 24 is small, so most changes are guards and stubs:

@aziontech/builder

  • esbuild node polyfills plugin: the built-in modules regex is now built only with the modules that have an unenv alias, a polyfill or an external entry. Node.js 24 lists node:test, node:test/reporters and node:sea in builtinModules, and the build failed trying to read a file named after them. Behavior on Node.js 22 is unchanged.
  • fs dev polyfill: F_OK, R_OK, W_OK and X_OK are read from fs.constants, because Node.js 24 removed them from the top level of fs.
  • crypto dev polyfill: exports argon2, argon2Sync, encapsulate and decapsulate (undefined on hosts without them).
  • Includes the Readable.toWeb / fromWeb stream polyfill.

@aziontech/unenv-preset

  • Stubs for Node.js 24 APIs that unenv does not cover: perf_hooks.timerify and eventLoopUtilization, url.URLPattern, v8.startCpuProfile, worker_threads.locks, fs.mkdtempDisposable, mkdtempDisposableSync and Utf8Stream. The ones that cannot work throw [azion] <api> is not implemented yet! when called, not when imported.
  • process.versions.node changes from 18.3.1 to 22.23.4, so libraries that check the Node.js version no longer take the Node.js 18 path. This is the one change that can alter the behavior of existing apps.

Repo

  • CI: unit tests run on Node.js 22 (latest patch) and 24. The install-dependencies action defaults to Node.js 24, the same as the release workflow.
  • .nvmrc points to lts/jod (Node.js 22) and engines.node is >=22.0.0.
  • presets: the Vercel telemetry test uses a real temp dir, because mock-fs 5.5.0 does not intercept the native fs.rmSync of Node.js 24.
  • Removes the unused download:cli script and the scripts/ folder.

Not in this PR

  • unenv stays at 2.0.0-rc.24. rc.25 only fixes readonly values in presets and brings no Node.js 24 coverage.
  • Cipher / Decipher in crypto need no change: they are already undefined on Node.js 22.
  • Changes in the bundler repo (Dockerfile, CI, sandbox) are tracked separately.

How it was verified

  • The full monorepo test suite passes on Node.js 24 and on Node.js 22.
  • An app importing node:url, perf_hooks, v8 and worker_threads generates a byte-identical bundle when built on Node.js 22 and on Node.js 24.
  • Not tested yet: real apps (Next, Astro, etc.) on Node.js 24 and the Azion runtime itself.

Type of change

  • feat: new feature
  • fix: bug fix
  • docs: / refactor: / test: / ci: / chore:
  • Breaking change

Bump

  • #major — breaking change
  • #minor — new backward-compatible feature
  • #patch — fix, refactor, docs
  • #none — no release (CI, internal docs)

Testing

  • Tests added or updated for the changed behavior
  • CI is green

Checklist

  • PR title follows Conventional Commits (type: description, optional [TICKET] prefix)
  • CHANGELOG.md updated, if the repository keeps one
  • No secrets, credentials or internal hostnames in code, logs or this description

…m polyfill

The polyfill replaced the native implementations of the host node:stream, and
its Readable.fromWeb never pushed any data (it returned { done, value } from
read() instead of calling push()), so a stream created with it never emitted
data or end. Next.js 16.4+ builds the HTML with Readable.fromWeb and toWeb, so
the render never finished and ISR pages were never revalidated on azion dev.

Install the polyfill versions only when the host does not provide them, and
make the fromWeb fallback push the data.
The download:cli script pointed to ./cli/scripts/download-cli.mjs, and there is
no cli folder in the repository.

The scripts folder only had code-review.mjs, from the AI code review workflow
that was already removed. Nothing references it and it imports
@actions/github, which is not a dependency.
…sions.node to 22

Add stubs for the Node.js 24 APIs that unenv does not cover yet:
- perf_hooks: timerify and eventLoopUtilization
- url: URLPattern
- v8: startCpuProfile
- worker_threads: locks
- fs: mkdtempDisposable, mkdtempDisposableSync and Utf8Stream

The stubs that cannot work throw "[azion] <api> is not implemented yet!"
when called, not when imported.

process.versions.node changes from 18.3.1 to 22.23.4 so libraries that
check the Node.js version no longer take the Node.js 18 path.
mock-fs 5.5.0 does not intercept the native fs.rmSync of Node.js 24, so
the "Should delete telemtry files" test failed there. Use a temp dir
created with fs.mkdtempSync, change into it and remove it in a finally
block. The test passes on Node.js 22 and 24.
…olyfills

- esbuild node polyfills plugin: build the built-in modules regex only
  with the modules that have an alias, a polyfill or an external entry.
  Node.js 24 lists node:test, node:test/reporters and node:sea in
  builtinModules and the build failed trying to read a file named after
  them.
- fs dev polyfill: read F_OK, R_OK, W_OK and X_OK from fs.constants,
  because Node.js 24 removed them from the top level of fs.
- crypto dev polyfill: export argon2, argon2Sync, encapsulate and
  decapsulate, which are undefined on a host without them.
…sion

- ci.yml: run the unit tests with a matrix of Node.js 22 (latest patch)
  and 24.
- install-dependencies action: default to Node.js 24, the same version
  used by the release workflow.
- .nvmrc: point to lts/jod (Node.js 22), the minimum supported version.
- package.json: set engines.node to >=22.0.0.
@github-actions

Copy link
Copy Markdown
Contributor

SCC Complexity Analysis

  • Title: feat: support Node.js 24 in the builder and unenv-preset
  • Author: jose-filho-azion
Metric Source Branch (feat/node-24-support) Target Branch (main) Difference
Complexity 4520 4512 8
Code 76332 76258 74

@pkg-pr-new

pkg-pr-new Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@aziontech/builder@500
npm i https://pkg.pr.new/@aziontech/presets@500
npm i https://pkg.pr.new/@aziontech/unenv-preset@500

commit: d9a083f

…e:sea

Do not fail the build when the code imports node:test,
node:test/reporters or node:sea, which have no polyfill.

- unenv-preset: add stubs for node:test, node:test/reporters and
  node:sea. They throw "[azion] <api> is not implemented yet!" when
  called, not when imported. sea.isSea() returns false.
- unenv-preset: in the fs polyfill, use mkdtempDisposable,
  mkdtempDisposableSync and Utf8Stream of the runtime when it has them,
  and define them with defineProperty because the runtime can define
  them as getters, as Node.js 24 does.
- builder: match the modules that exist only with the node: prefix
  (node:test, node:sea, node:sqlite) only with the prefix, so an npm
  package named test, sea or sqlite is not taken as a built-in module.
- builder: handle the same modules on Node.js 22 and 24 by also using
  the node: keys of the alias map, not only builtinModules.
@github-actions

Copy link
Copy Markdown
Contributor

SCC Complexity Analysis

  • Title: feat: support Node.js 24 in the builder and unenv-preset
  • Author: jose-filho-azion
Metric Source Branch (feat/node-24-support) Target Branch (main) Difference
Complexity 4531 4512 19
Code 76422 76258 164

The fs polyfill used by azbundler dev exports a fixed list of names, so
mkdtempDisposableSync and Utf8Stream were undefined and calling them
failed with "(void 0) is not a function".

Export them as stubs that throw "[azion] <api> is not implemented yet!"
when called, the same error as the production polyfill.
…hangesets

azion dev is the usage with the Azion CLI and azbundler dev is the usage
with the bundler. The polyfills and the changesets are about the bundler.
@github-actions

Copy link
Copy Markdown
Contributor

SCC Complexity Analysis

  • Title: feat: support Node.js 24 in the builder and unenv-preset
  • Author: jose-filho-azion
Metric Source Branch (feat/node-24-support) Target Branch (main) Difference
Complexity 4531 4512 19
Code 76438 76258 180

@github-actions

Copy link
Copy Markdown
Contributor

SCC Complexity Analysis

  • Title: feat: support Node.js 24 in the builder and unenv-preset
  • Author: jose-filho-azion
Metric Source Branch (feat/node-24-support) Target Branch (main) Difference
Complexity 4540 4521 19
Code 76835 76655 180

Next.js reads the body of a server action with pipeline from
node:stream/promises, and unenv only has stubs for it, so a server action
failed with "[unenv] stream.promises.pipeline is not implemented yet!".

- unenv-preset: add the stream/promises polyfill. It uses the promises of
  the node:stream of the runtime when it has them, and otherwise builds
  pipeline and finished on the callback versions. The end option is not
  supported by the fallback.
- builder: pass pipeline, finished and promises of the host node:stream
  in the stream context used by azbundler dev, add the stream/promises
  polyfill for it and export them in the node:stream polyfill.
@github-actions

Copy link
Copy Markdown
Contributor

SCC Complexity Analysis

  • Title: feat: support Node.js 24 in the builder and unenv-preset
  • Author: jose-filho-azion
Metric Source Branch (feat/node-24-support) Target Branch (main) Difference
Complexity 4563 4521 42
Code 76908 76655 253

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant