drawille-canvas HTML5 Canvas API for Terminal

0.1.3 · abandoned · verified Tue Apr 21

The `drawille-canvas` package provides an implementation of a subset of the HTML5 Canvas 2D API, specifically designed for rendering graphics within a terminal environment. It achieves this by utilizing Unicode braille characters through the underlying `drawille` library. Currently at version `0.1.3`, the project appears to be in an early, unmaintained, or abandoned state. The README explicitly notes improved performance on Node.js `v0.11` compared to `v0.10`, which are extremely old Node.js runtime versions, indicating the package was developed for historical environments. There is no clear release cadence, and active development for modern Node.js environments is highly improbable. Its primary value proposition was offering a familiar imperative Canvas-like drawing API for text-based interfaces.

Common errors

```
TypeError: Canvas is not a constructor
```
cause Attempting to import `Canvas` using ES Module syntax (`import`) or incorrect CommonJS destructuring, instead of the expected CommonJS default export.

fix Use `const Canvas = require('drawille-canvas');` to correctly import the module.
```
TypeError: Cannot read properties of undefined (reading 'fillRect')
```
cause This error occurs when attempting to call a method like `fillRect` on a variable that is not an initialized `Canvas` instance, often due to an incorrect import or instantiation.

fix Ensure `const canvas = new Canvas(width, height);` has been called successfully, and methods are called on the `canvas` object (or a context derived from it if applicable, though for this library it's directly on `canvas`).
```
Error: Cannot find module 'drawille'
```
cause The required `drawille` package, which is a peer or direct dependency, is not installed in the project.

fix Install the dependency explicitly: `npm install drawille`.

Warnings

gotcha The package was developed for very old Node.js versions (v0.10/v0.11). Compatibility and performance with modern Node.js runtimes (v12+) are not guaranteed and may lead to unexpected errors or degraded performance.
Fix: Consider using alternative, actively maintained terminal UI/graphics libraries for modern Node.js projects, or a carefully isolated environment with an older Node.js version if legacy code must be run.
gotcha The Canvas API implementation is incomplete, notably missing crucial methods such as `fill()`, `arc()`, and `arcTo()`. This limits the complexity of graphics that can be easily rendered.
Fix: Review the API documentation thoroughly before relying on specific Canvas 2D context methods. For missing functionality, custom workarounds using existing primitives or a different library would be necessary.
gotcha As an abandoned project (version 0.1.3), it is highly unlikely to receive bug fixes, security updates, or new features. Relying on it for production systems introduces maintenance risks.
Fix: Evaluate the necessity of this specific library. If terminal graphics are essential, explore more current and actively maintained alternatives in the Node.js ecosystem.
gotcha The output relies on braille characters, which might not render correctly across all terminal emulators or fonts, leading to inconsistent visual results.
Fix: Test the output extensively in the target terminal environment. Ensure the terminal supports Unicode braille characters and that a suitable font is configured.

Install

npm install drawille-canvas-blessed-contrib npm
yarn add drawille-canvas-blessed-contrib yarn
pnpm add drawille-canvas-blessed-contrib pnpm

Imports

Canvas
wrong:
```
import { Canvas } from 'drawille-canvas';
import Canvas from 'drawille-canvas';
const { Canvas } = require('drawille-canvas');
```
correct:
```
const Canvas = require('drawille-canvas');
```
This package primarily supports CommonJS (`require`) syntax due to its age. Direct ES Module (`import`) usage is unlikely to work without a CommonJS wrapper or bundler.

Quickstart

Illustrates how to initialize a Canvas, draw basic shapes like rectangles and lines, clear areas, apply transformations (translate, rotate), and output the braille-rendered frame to the console.

const Canvas = require('drawille-canvas');

const width = 80;
const height = 20;
const canvas = new Canvas(width, height);
const ctx = canvas; // CanvasRenderingContext2D methods are directly on the canvas object

// Draw a rectangle
ctx.fillRect(0, 0, 10, 5);

// Draw a line
ctx.beginPath();
ctx.moveTo(15, 2);
ctx.lineTo(25, 10);
ctx.stroke();

// Clear a portion
ctx.clearRect(2, 2, 3, 3);

// Translate and draw another rectangle
ctx.save();
ctx.translate(30, 5);
ctx.rotate(Math.PI / 4); // Rotate by 45 degrees
ctx.fillRect(0, 0, 8, 4);
ctx.restore();

// Draw something more complex to fill the space
for (let i = 0; i < 10; i++) {
  ctx.beginPath();
  ctx.moveTo(width - 1 - i * 3, 0);
  ctx.lineTo(width - 1 - i * 3, height - 1);
  ctx.stroke();
}

// Output the generated braille frame to the console
console.log(canvas.frame());

view raw JSON →