Canvas Dependency Resolution

Status: Problem Clear

Problem

The canvas npm package does not have pre-built binaries for Node.js 24, which is blocking the Node.js 24 upgrade (#2011). The canvas package is currently listed as a devDependency in frontend/package.json, but there are conflicting reports about whether our tests work without it.

The issue manifests when running tests without the canvas package installed:

Error: Cannot find module 'canvas'
Require stack:
- /home/jenkins/workspace/PermaplanT_MR-1905/frontend/node_modules/konva/lib/index-node.js

This error occurs because the Konva library uses the canvas library internally for Node.js tests. The canvas package is only referenced in vite.config.ts in our codebase, with no direct imports in our source code.

Constraints

  1. Must not break existing test coverage
  2. Must be compatible with Node.js 24
  3. Should work in DevContainer, CI, and local development environments
  4. Must support Konva testing requirements
  5. Should minimize maintenance burden
  6. Must enable the Node.js 24 upgrade (#2011)

Assumptions

  1. Canvas is unused in our source code (only referenced in vite.config.ts with test exclusions)
  2. RESOLVED: Konva requires canvas for Node.js testing
    • Testing confirmed that removing canvas breaks 17 test suites
    • Konva's index-node.js has a hard dependency on the canvas module
    • Conflicting test reports were based on incomplete test runs
  3. Alternative solutions that don't involve removing canvas are necessary
  4. Upgrading to Konva 10 might resolve the issue entirely (still needs investigation)
  5. Other alternatives (mocking, native binaries, or waiting) may be necessary

Solutions

Alternative A: Remove canvas dependency entirely

Remove the canvas package from package.json and verify all tests pass without it (as proposed in MR !1892).

Status: DOES NOT WORK - Tested and confirmed to break 17 test suites

Investigation Results (2025-11-18):

  • Removed canvas from package.json and ran full test suite
  • Result: 17 test suites failed with "Cannot find module 'canvas'"
  • Root cause: Konva's Node.js entry point (node_modules/konva/lib/index-node.js) directly requires the canvas module
  • This breaks tests that import Konva or any components using Konva

Pros:

  • Simplest solution (if it worked)
  • Removes unused dependency
  • No migration or compatibility concerns
  • Enables immediate Node.js 24 upgrade

Cons:

  • Breaks 17 test suites - Konva requires canvas for Node.js testing
  • Conflicting test reports were inaccurate or based on incomplete test runs
  • This is not a viable solution

Alternative B: Upgrade to Konva 10

Upgrade Konva to version 10, which according to the react-konva documentation may not require the canvas package.

Pros:

  • May eliminate the canvas dependency requirement entirely
  • Keeps up-to-date with the latest Konva version
  • Potential performance and feature improvements

Cons:

  • May introduce breaking changes requiring code updates
  • Requires testing migration effort
  • Konva 10 compatibility with our codebase needs verification

Investigation needed:

  • Check Konva 10 changelog for breaking changes
  • Verify that Konva 10 doesn't require canvas for Node.js testing
  • Test compatibility with our current Konva usage patterns

Alternative C: Upgrade canvas to a newer version

Upgrade to a newer version of the canvas package that supports Node.js 24.

Pros:

  • Maintains existing test setup
  • Minimal code changes required

Cons:

  • Canvas may not have released Node.js 24 compatible binaries yet
  • Adds native build complexity (C++ compilation)
  • Increases installation time and failure points
  • May not be available immediately

Investigation needed:

  • Check canvas repository for Node.js 24 support roadmap
  • Verify if newer canvas versions are available with Node.js 24 binaries
  • Test build process in all environments

Alternative D: Mock canvas in tests

Replace the real canvas implementation with a mock implementation specifically for testing.

Pros:

  • Lightweight solution
  • No native dependencies
  • Fast installation and testing
  • Node.js 24 compatible

Cons:

  • Less realistic testing
  • May not catch canvas-related bugs
  • Additional maintenance for mock implementation
  • May not satisfy Konva's internal requirements

Investigation needed:

  • Determine if Konva tests can work with mocked canvas
  • Research mocking approaches (jsdom-canvas, canvas-mock, custom mock)
  • Verify test coverage is maintained

Alternative E: Wait for canvas Node.js 24 support

Postpone the Node.js 24 upgrade until the canvas package releases pre-built binaries for Node.js 24.

Pros:

  • No code changes needed
  • Maintains current setup

Cons:

  • Blocks Node.js 24 upgrade indefinitely
  • No clear timeline for when support will be available
  • Delays other improvements that depend on Node.js 24
  • Goes against project goals of staying up-to-date

Investigation needed:

  • Check canvas repository roadmap and issue tracker
  • Assess timeline for Node.js 24 support

Decision

Rationale

Implications

Notes

  • Issue #2294: Decision issue for this document
  • Issue #2407: Konva 10 upgrade investigation (follow-up)
  • Issue #2011: Node.js 24 upgrade (blocked by this decision)
  • Issue #1863: Previous canvas-related issues
  • MR !1892: Proposes removing canvas dependency
  • Current package: canvas@2.11.2 in frontend/package.json (devDependencies)
  • Current usage: Only referenced in vite.config.ts, no imports in source code
  • Test failure details from @e12024013 show Konva's index-node.js requires canvas
  • @markus.raab suggested checking Konva 10 upgrade as potential solution (2025-11-10)
  • According to react-konva Next.js documentation, Konva 10 may resolve this issue
  • Problem Clear status reached on 2025-12-14 (MR !1961)
  • Alternative A confirmed not viable through testing; remaining alternatives need Konva 10 investigation

Status: Problem Clear

Next Steps:

  1. Investigate Konva 10 upgrade compatibility (#2407)
  2. Evaluate remaining solutions (B, C, D, E) once Konva 10 investigation is complete
  3. Move to "Solutions Clear" once all alternatives are fully explored