Skip to content
Nilay Kabariya

Entry No.099·Fixes··3 min read

jsdom 31: getContext needs @napi-rs/canvas, and load moved

jsdom 31 returns null from getContext with canvas installed: it now loads @napi-rs/canvas. And load no longer fires on document. Both tested.

by Nilay#jsdom#vitest#node#testingFIXED

The error, verbatim

Jump to the fix ↓
Not implemented: HTMLCanvasElement's getContext() method: without installing the @napi-rs/canvas npm package

The fix that worked

On jsdom 31, install the new backend:

npm install --save-dev @napi-rs/canvas
Not it? Every cause, tested ↓

Tested on

jsdom
30.1.3 and 31.0.0
Backends
canvas 3.2.3, @napi-rs/canvas 1.1.0
Test runner
Vitest 5 (environment jsdom); jest-environment-jsdom 30.5.2 dependency range from npm
Node / OS
24.22.2 / Ubuntu and Windows Server 2025 (GitHub Actions)

✓ Last re-run on GitHub Actions · see the run · all repros

If your canvas tests broke right after a jsdom upgrade, look closely at the message. It used to end in “without installing the canvas npm package”. On jsdom 31 it ends in “without installing the @napi-rs/canvas npm package”. That one word is the whole story: jsdom 31.0.0 (November 5, 2026) switched its optional canvas backend from canvas to @napi-rs/canvas, so the package that made getContext('2d') work for years now does nothing.

On jsdom 31, install @napi-rs/canvas (you can remove canvas):

npm install --save-dev @napi-rs/canvas

Every combination, on two operating systems

The two backends are not interchangeable. I installed jsdom 30 and 31 each with no backend, with canvas and with @napi-rs/canvas, on November 9, 2026, and asked for a 2D context:

Terminal on GitHub Actions: jsdom 30.1.3 returns a CanvasRenderingContext2D only with canvas 3.2.3 and logs without installing the canvas npm package otherwise; jsdom 31.0.0 returns a context only with @napi-rs/canvas 1.1.0 and logs without installing the @napi-rs/canvas npm package otherwise, including when canvas is installed; Vitest 5 on jsdom 31 fails without a backend.
Linux run; the Windows run on the same day printed the same lines. Full log.
nothing installed canvas 3.2.3 @napi-rs/canvas 1.1.0
jsdom 30.1.3 null works null
jsdom 31.0.0 null null works

So the fix depends on the jsdom you actually have, and that differs by test runner. Run npm ls jsdom to see it:

  • Vitest doesn’t bring its own jsdom: its peer range is *, so you get whatever you installed, and a fresh npm install -D jsdom on or after November 5 gives you 31. Vitest users are the ones hitting this.
  • Jest brings jsdom through jest-environment-jsdom, and its current release (30.5.2) depends on jsdom ^26.1.0. So a Jest project is on jsdom 26, where canvas is still the right backend, unless you’ve overridden it.

If npm ls jsdom shows anything below 31, keep canvas; installing @napi-rs/canvas there changes nothing.

Why the old answers don’t help

Almost every answer you’ll find for this message says npm install canvas, and most date from 2018 to 2023. That was correct for every jsdom up to 30. On 31 it’s the one install that leaves you exactly where you started, with no hint beyond the changed package name at the end of the warning. If you have canvas in devDependencies only for jsdom, it can go once you’re on 31, and it’s worth removing: leaving both installed makes it easy to misread which one is doing the work.

One more thing the run showed: it’s a warning, not an exception. jsdom reports it on its virtual console and getContext simply returns null, so the test usually fails further on, wherever it first uses the context. If a canvas test fails in an odd place, look higher up the output for the “Not implemented” line.

The other change in the same release: load on document

If a test also started hanging or skipping a step after the upgrade, check for document.addEventListener('load', …). I registered three listeners in a page loaded with scripts enabled and logged which fired:

DOMContentLoaded load on document load on window
jsdom 30.1.3 fired fired fired
jsdom 31.0.0 fired didn’t fire fired

Same result on Linux and Windows. jsdom 31 now dispatches load only on window, which is what browsers do; jsdom 30 also delivered it to listeners on document. Code that waited for load on document passed in tests for years while it never would have fired in a real browser, and now the test catches it. The fix is the browser-correct one:

window.addEventListener('load', onLoad);   // not document.addEventListener('load', …)

The run

Ubuntu and Windows Server 2025 runners on GitHub Actions, Node 24.22.2, November 9, 2026. Each of the six combinations was a fresh folder with only jsdom and the backend installed, running a three-line script that creates a <canvas> and calls getContext('2d'), with jsdom’s virtual console capturing the warning. The Vitest part used Vitest 5 with --environment jsdom on jsdom 31, before and after adding @napi-rs/canvas. The load test registered listeners on document and window in a page with runScripts: 'dangerously' (run 42574390965). The script and both runs are public.

— N.K., end of entry No.099

Useful? Pass it on:Post on XFollow @EmotionalMatter

Related entries

  1. No.041

    Vitest 4 to 5 migration: 6 breaking changes, tested

    Six behaviours that passed on Vitest 4.1.11 failed or changed on 5.0.3, each with a clear message and a one-line fix. The sneaky one is test.each titles: snapshot keys change, and locally Vitest 5 quietly writes new snapshots instead of failing.

    TESTED5 min
  2. No.105

    ERR_PNPM_IGNORED_BUILDS: onlyBuiltDependencies no longer works

    pnpm 11 and 12 fail installs with ERR_PNPM_IGNORED_BUILDS and ignore onlyBuiltDependencies. pnpm 10, 11 and 12 tested: the allowBuilds setting that passes.

    > Error: ERR_PNPM_IGNORED_BUILDS

    FIXED4 min
  3. No.103

    Fix: npm error code EALLOWGIT, tested

    npm error code EALLOWGIT: npm 12 blocks git dependencies by default. Every git case tested on npm 12.2.2 and 11.21.2, plus allow-git values.

    > npm error code EALLOWGIT

    FIXED6 min

tip: paste the exact error text