How Node.js and V8 keep each other working - workflows, challenges and tips | Joyee Cheung's BlogHow Node.js and V8 keep each other working - workflows, challenges and tips<br>Joyee Cheung's Blog

Home Archive About RSS

How Node.js and V8 keep each other working - workflows, challenges and tips<br>2026-05-18 | Tech | V8Node.js<br>Recently I’ve found myself repeating the same explanations to different people about how to test a V8 patch in Node.js, how to patch the Node.js fork run in V8’s integration CI, or how to get these patches into their repositories/CIs. I’ve also been helping out with some of the V8 maintenance tasks in Node.js recently, which refreshed some of my knowledge about how things work these days. To reduce the parrotting, here is my attempt to write down the current state of things, the challenges I’ve observed and some tips on how to handle cross-project patches.

A map of repositories

Before we begin, here’s a quick map of the repositories involved in the Node.js and V8 integration:

nodejs/node: the main Node.js repository.

The main branch is the primary development branch.

The canary-base branch is the base for testing newer versions of V8.

nodejs/node-v8: the repository for testing V8 integration with Node.js. Known as “canary”.

The main branch is used to run a daily workflow that tests canary-base with the latest V8 lkgr (Last-Known-Good-Revision) branch.

The canary branch is updated daily by the aforementioned workflow if it succeeds, and gets built by a daily release CI to produce v8-canary builds.

v8/v8: the main V8 repository.

v8/node: the repository for testing Node.js integration with V8.

The node-ci-YYYY-MM-DD branch e.g. node-ci-2026-04-16 is used in V8’s integration CI, and is cut from the Node.js main branch with V8’s own patches applied on top every few months.

v8/node-ci: the repository for managing V8’s Node.js integration CI, which includes the build scripts and dependency settings.

deps/v8 in Node.js

I wrote about this several years ago in this blog post, most of that is still true today, but here’s a refreshed description of it.

How Node.js maintains V8 updates

The source of truth about this lives in this document. Here is my rephrase of what the process means in practice.

Node.js maintains a fork of V8 in this deps/v8 directory. On the main branch, this directory is regularly updated to stay in sync with the most recent V8 stable releases. It also “floats” some V8 patches on top - usually changes that have already landed in V8’s main branch but backported early to Node.js’s fork to speed up the roundtrip, or minimal platform-specific patches that make Node.js work with platforms/toolchains that V8 doesn’t support upstream. Other kinds of modifications to deps/v8 are generally expected to be reviewed and landed in the V8 upstream, in order to minimize the discrepancies and the maintenance burden.

Roughly every month, when a new V8 stable release is out, a big PR like this will be opened to update the deps/v8 directory to the new version and make it work with Node.js. In the many years I’ve been with the project, it’s usually Michaël Zasso who takes on the heroic task of opening these huge PRs and collaborating with everyone to get it working on the many platforms in the Node.js CI.

Other than the main branch, there is a canary-base branch in Node.js that serves as the base branch for testing newer versions of V8. Every day, a workflow runs in the nodejs/node-v8 repository to pull the canary-base branch of Node.js, updates its deps/v8 directory to be a copy of V8’s lkgr (Last-Known-Good-Revision) branch with floated patches on top, and checks if it builds. This canary workflow helps contributors stay on top of the upcoming breakages before they pile up in the big upgrade PRs. When the workflow succeeds, it updates the canary branch in nodejs/node-v8, and a daily release CI will build it to produce binaries in the v8-canary release channel.

How Node.js builds V8

This is the part that seems to surprise many new Node.js contributors - the V8 upstream uses GN as the build system, while Node.js uses GYP (or technically speaking, it’s a GYP-next fork living in tools/gyp). This is a legacy build system used by Chromium/V8 before they switched to GN, but Node.js has been stuck with it due to various downstream compatibility reasons - there have been many discussions (1, 2, 3) about moving away from GYP, but for now GYP is still in use. A major part of maintaining the V8 updates in Node.js comes down to translating upstream GN config changes into GYP config changes - there are some scripts that help with the translation, though the difficult part is often to ensure the intent of the changes remains the same or is adapted correctly for Node.js’s use cases. The GYP files for building V8 don’t live in deps/v8 but in tools/v8_gypfiles to avoid conflicts.

As a server-side runtime, Node.js supports many operating systems / architectures / toolchains, both in building...