Repository navigation
Reconsider ABI stability requirement for V8 updates in majors #1852
Description
Opening this to discuss whether we should stop treating ABI compatibility changes as blockers for V8 updates in major releases.
We’ve been hitting the same issue repeatedly. v26.0.0 was already delayed for V8 14.6, and that version became outdated almost immediately with Chrome 148 (V8 14.8) going stable.
From the TSC thread, the main pain point is that ABI stability adds pressure and slows down landing V8 updates. Removing that constraint would let updates land when they’re actually ready instead of forcing timing compromises.
There was also the suggestion to drop ABI stability guarantees in majors and push the ecosystem more toward N-API or FFI.
This is probably too late for v26, but could make sense starting in v27.
cc: @targos, who has handled most (if not all) V8 updates for quite a long time
Activity
richardlau commentedon Apr 28, 2026
FTR the suggestion to drop ABI stability was made separately from (my) suggestion that if we do that the policy shift should happen in a major. We do include the V8 headers in the Node.js header tarball for addons so it needs to be clearly communicated if we make the change.
joyeecheung commentedon Apr 28, 2026
In general I am in favor of decoupling ABI versioning with Node.js semantic versioning, though I don't think it's the same as "dropping ABI stability" - which implies we no longer version the ABI at all.
To me it seems being able to bump a new ABI version in the lifetime of a Node.js major release at least before it goes LTS would be enough as a relief and is relatively low risk - most addon prebuild tools are already pre building based on ABI versions, not Node.js versions. But not having versions for breaking changes in the ABI would be too disruptive.
aduh95 commentedon Apr 28, 2026
Worth noting that, as of Node.js 27, we'll be releasing versions before 27.0.0 which might include semver-major changes, and possibly ABI-breaking changes – the intent being explicitely that we want to bump the V8 version before releasing 27.0.0.
IIUC the proposal is to extend that to the "Current" phase? And LTS as well?
mcollina commentedon Apr 28, 2026
I think we should define where we stop.
Personally, I'm very comfortable in having them in current, a bit less so in LTS, and as an "absolutely not" in maintenance.
RafaelGSS commentedon Apr 28, 2026
That's right. I guess we won't have to delay semver-majors release anymore during the Alpha version. Theoretically, V8 14.6 could be released from April 22th until Oct Xth, which should make the process much easier.
mcollina commentedon Apr 29, 2026
cc @nodejs/node-api wdyt? What's the state of n-api vs nan adoption right now?
legendecas commentedon May 1, 2026
Node-API is not affected by V8 ABI stability by design. So I think this does not impact the ABI stability guarantee provided by Node-API, and Node-API could be an alternative that could be a recommended way to build addons.
Regarding the node-api vs nan adoption, I don't have a specific figure. But here is a rough comparison:
Note that node-addon-api does not count for all node-api usages. Addons using node-api with other programming languages does not rely on node-addon-api (which is a C++ wrapper). There are also wrappers like https://github.com/napi-rs/napi-rs, and this is another reason that addons should use Node-API instead of the V8 api directly as the cross language binding could be more stable and easier to build.
RafaelGSS commentedon May 4, 2026
I guess we can close it and see if Node.js v27 Alpha will solve it. Otherwise, we re-open that.
targos commentedon May 4, 2026
The alpha will not solve it.
RafaelGSS commentedon May 4, 2026
Can you elaborate?
targos commentedon May 4, 2026
Because the alpha stage will replace odd-numbered versions. It won't change anything wrt. LTS versions, which will very quickly become outdated if we can't update V8 (there's a new version every 4 weeks).
RafaelGSS commentedon May 5, 2026
In my understanding, it will. We won't need to rush to land V8 15.x in April, for instance, it could be landed anytime until the stable version (released in October)
7 remaining items
targos commentedon May 6, 2026
This just moves the problem by six months...
targos commentedon May 6, 2026
Actually, I read https://nodejs.org/fr/blog/announcements/evolving-the-nodejs-release-schedule again, and that's not what it's saying.
With the documented plan, we would be allowed to make major V8 updates in alpha between October and April. That's exactly the same window as before.
joyeecheung commentedon May 6, 2026
I think the discrepancy comes from
Currently 1 and 2 both happen in April. Combined with 4 this means we have to rush. If we can change it so that, for example, 2 happen in October (when it goes LTS), but 1 happens in April (when it goes stable but not yet LTS) we have a 6-month window to still update V8 to some extent, ideally in the latter part of that window the V8 version on that release goes into some sort of "maintenance mode", so that when it's close to October again, the V8 version on that release is considered "done" and we will focus on getting the new V8 version ready for the alpha release. And because it's alpha it's not that hard a deadline for breaking changes, so we have some breathing room. Even after the next April, because we are allowed to break the ABI during the stable phase, we still have breathing room likely well into September or something. This means LTS's V8 version will be closer to the V8 version that's stable when it goes LTS in the second October, while currently it's close to the version that's stable when it is released in April (and is where the rush comes from, if we don't manage to get the "latest in April" version in, the older version will need to be maintained for ~2 years).
richardlau commentedon May 12, 2026
We might also be limited by build toolchains. So far we have not bumped minimum C/C++ compiler levels during the lifetime of a Node.js release line (with the exception of a mid-life Xcode bump that was forced by Apple due to gatekeeper changes). Most of the compiler bumps have been driven by V8 -- I have no idea if this will be better/worse/the same now we have switched over to clang (but note upstream V8 have their own fork of clang/llvm that they use to build with, which is not the released versions of clang in e.g. Linux distros).
RafaelGSS commentedon May 18, 2026
So the proposed strategy would be allowing ABI-breaking changes during the 'Current' phase?
joyeecheung commentedon May 21, 2026
Another thing I noticed in nodejs/node#63475 that's worth including in the ABI stability is that V8 serialization format changes were historically considered semver-major. If our goal is to be able to upgrade V8 without bumping major (at least before LTS), it might be worth to include this part into ABI stability/versioning as well.
joyeecheung commentedon May 21, 2026
My 2cents in the context of the proposed new schedule: yes for alpha, maybe for stable, only exceptional (mostly for security) for LTS; or, to experiment, yes for alpha, only exceptional since stable.
aduh95 commentedon May 21, 2026
Does ABI unstability impact
v8.serialize/v8.deserialize? If so, that could potentially affect the ecosystem more than the re-compilation of third-party addons (not saying it'd be a deal-breaker, but certainly worth documenting)legendecas commentedon May 24, 2026
Hmm, I think V8 provides a backward compatible guarantee on the format of
v8.serialize/v8.deserialize, as in its own version mechanism.If this breaks, it should be a V8 bug. It is also documented in Node.js doc: https://nodejs.org/api/v8.html#serialization-api i.e. a newer V8 can read the output serialized by an older V8, but not vice-versa. So users should not use the output of a new Node.js version to feed into an older Node.js
v8.deserialize.mcollina commentedon May 27, 2026
Removing from the TSC meeting agend, @RafaelGSS re-add in case you need. There does not seem to be any blockers, just technical details to fill.
RafaelGSS commentedon May 28, 2026
Hi folks, so I guess we could start a small announcement to get involvement from the community. I thought something like:
What do you think? @targos @joyeecheung @legendecas
aduh95 commentedon May 28, 2026
I suggest we move the discussion to a PR updating the docs
RafaelGSS commentedon Jun 29, 2026
Where is the best place to update the docs about that? I opened nodejs/node#64196, but I'm not convinced this is "clear" enough. I'm still learning towards a nodejs.org blog post about that.
doc: update V8 ABI release policy