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/canvasNot 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
Contents
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/canvasEvery 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:

| 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 freshnpm install -D jsdomon 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, wherecanvasis 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