update-v8

name: update-v8 description: Step-by-step guide for updating the V8 JavaScript engine in workerd, including patch rebasing, dependency updates, integrity hashes, and verification. Load this skill when performing or assisting with a V8 version bump.

Updating V8 in workerd

V8 updates are high-risk changes that require careful patch management and human judgment for merge conflicts. This skill covers the full process. Always confirm the target version with the developer before starting.

See also: docs/v8-updates.md for the original reference document.

Always communicate and confirm with the developer at each step. Never take irreversible actions (like dropping patches or updating hashes) without explicit confirmation.

Prerequisites

• depot_tools installed and on $PATH (setup guide)
• A local V8 checkout (outside the workerd repo to avoid confusing Bazel):

  mkdir v8 && cd v8 && fetch v8
  

Step 1: Identify the target version

Check chromiumdash.appspot.com for the latest V8 version used by Chrome Beta. Confirm the target <new_version> with the developer.

Find the current version in build/deps/v8.MODULE.bazel:

VERSION = "14.5.201.6"    # example — check the actual file

We'll call this <old_version>.

Step 2: Sync local V8 to the current workerd version

cd <path_to_v8>/v8
git checkout <old_version>
gclient sync

Step 3: Apply workerd's patches onto a branch

git checkout -b workerd-patches
git am <path_to_workerd>/patches/v8/*

There are multiple patches in patches/v8/. These include workerd-specific customizations:

Step 4: Rebase patches onto the new V8 version

git rebase --onto <new_version> <old_version>

This is where most of the work happens. Expect conflicts. Key guidance:

• Build-system patches (dependency paths, Bazel config) conflict most often as upstream V8 restructures its build.
• API patches (new methods on V8 classes) may conflict if upstream changed the surrounding code.
• Always preserve workerd's intent — understand what each patch does before resolving conflicts. The patch filenames are descriptive.
• Do not drop patches without explicit confirmation from the developer.
• Do not auto-resolve conflicts — flag them for human review. Merge conflicts in V8 patches almost always require human judgment.

Step 5: Regenerate patches

git format-patch --full-index -k --no-signature --no-stat --zero-commit <new_version>

This produces numbered .patch files in the current directory.

Step 6: Replace patches in workerd

Always confirm with the human before replacing patches. If any patches were dropped or added, the human needs to review the changes.

rm <path_to_workerd>/patches/v8/*
cp *.patch <path_to_workerd>/patches/v8/

Step 7: Update build/deps/v8.MODULE.bazel

Three things need updating:

1. VERSION: Set to <new_version>.

2. INTEGRITY: Compute the sha256 hash of the new tarball:

   curl -sL "https://github.com/v8/v8/archive/refs/tags/<new_version>.tar.gz" -o v8.tar.gz
   openssl dgst -sha256 -binary v8.tar.gz | openssl base64 -A
   

   Format: "sha256-<base64_hash>=". Alternatively, attempt a build and copy the expected hash from Bazel's mismatch error.

3. PATCHES: Update the list if patches were added, removed, or renamed. The list must match the filenames in patches/v8/ exactly, in order.

Step 8: Update V8's dependencies

V8 depends on several libraries that are pinned in build/deps/v8.MODULE.bazel and build/deps/deps.jsonc. Check the local V8 checkout's DEPS file for commit versions:

cat <path_to_v8>/v8/DEPS

Dependencies to check and update:

For dependencies in deps.jsonc, you can use the update script:

python3 build/deps/update-deps.py perfetto
python3 build/deps/update-deps.py simdutf

This fetches the latest version, computes integrity hashes, and regenerates the gen/ MODULE.bazel fragments. Do not hand-edit files in build/deps/gen/.

Step 9: Build and test

# Full build
just build

# Full test suite
just test

Watch for:

• Build failures from V8 API changes: V8 may deprecate or change APIs between versions. Search for deprecation warnings in the build output. Common areas affected:

  • src/workerd/jsg/ — V8 binding layer, most directly affected
  • src/workerd/api/ — APIs that interact with V8 types directly
  • src/workerd/io/worker.c++ — Isolate creation and configuration

• Test failures from behavior changes: V8 may change observable JS behavior. Check:

  • just test //src/workerd/jsg/... — JSG binding tests
  • just test //src/workerd/api/tests/... — API tests
  • Node.js compatibility tests (just node-test)
  • Web Platform Tests (just wpt-test)

• New V8 deprecation warnings: These are future breakage signals. Document them in the PR description even if tests pass.

Step 10: Commit and submit

Prompt the user to commit the changes and push for review.

Never push the branch for review without a human review of the patch changes.

You May prepare the draft PR text for the user. The PR should include:

• Updated build/deps/v8.MODULE.bazel (version, integrity, patches list)
• Updated patches in patches/v8/
• Updated dependency versions if changed
• Any C++ fixes for V8 API changes
• PR description listing: old version, new version, patches that required conflict resolution, any deprecation warnings observed, and any behavior changes noted

Checklist

• Target V8 version confirmed with developer
• Local V8 checked out and synced to old version
• workerd patches applied and rebased onto new version
• Conflicts resolved with human review (no auto-resolution)
• Patches regenerated with git format-patch
• Old patches replaced with new patches in patches/v8/
• VERSION updated in v8.MODULE.bazel
• INTEGRITY updated in v8.MODULE.bazel
• PATCHES list updated if patches added/removed/renamed
• V8 dependencies checked and updated (ICU, perfetto, simdutf)
• just build succeeds
• just test passes (or failures documented and explained)
• No new patches dropped without explicit confirmation
• PR description documents version change, conflict resolutions, and deprecation warnings

Troubleshooting

Bazel integrity mismatch: If you see expected sha256-... but got sha256-..., copy the "got" hash into the INTEGRITY field. This happens when the hash was computed incorrectly or the tarball was re-generated by GitHub.

Patch won't apply: A patch that applied cleanly during git am but fails in Bazel means the git format-patch output differs from what Bazel expects. Verify you used --full-index -k --no-signature --no-stat --zero-commit flags. Also verify patch order matches the PATCHES list.

ICU build failures: ICU is a Chromium fork fetched via git_repository. If the commit in v8.MODULE.bazel is wrong, you'll see missing-file or compilation errors in ICU. Cross-reference with V8's DEPS file for the correct commit.

update-deps.py fails: The script requires network access to fetch versions. If a dependency's GitHub release format changed, you may need to update the version manually in deps.jsonc and run python3 build/deps/update-deps.py to regenerate hashes.