Skip to content
Apexify.jsDocs
Apexify.js version v5.4.5

Node / Canvas · guide

Canvas and createCanvas

Understand createCanvas, CanvasConfig, CanvasResults, validation, backgrounds, rendering order, and the core Node canvas workflow.

apexify.jsRuntime: nodeCURRENTSince 6.0.0

Signature & types

SOURCEtypescript
typescript
Studio
await painter.createCanvas(  config: CanvasConfig,  painterOpts?: { resolveAssetRefs?: boolean }): Promise<CanvasResults>;

CanvasConfig and CanvasResults are the primary configuration and result contracts for the Node canvas workflow. The signature-types heading remains canonical so legacy deep links continue to resolve after the DOC-3 component migration.

Prerequisites

  • Apexify.js 6.0.0 installed in a Node runtime.
  • An ApexPainter instance configured for buffer output.
  • Explicit width and height for predictable production output unless an inherited image/video source determines them.

Minimal workflow

  1. Import ApexPainter from apexify.js.
  2. Create a painter with buffer output.
  3. Call createCanvas with explicit dimensions and one primary fill.
  4. Use buffer as the PNG output or composite additional image/text/chart content.
Node canvas: available

Return value (CanvasResults)

FeatureFieldMeaning
bufferBufferPNG bytes for saving, output, or later composition
canvasCanvasConfigEffective configuration reference after inherited sizing or other mutations

Defaults and validation

FeatureStatusNotes
width / heightDefaults to 500 × 500Prefer explicit production dimensions unless customBg.inherit or videoBg.inherit determines size
primary backgroundMutually exclusiveUse at most one of colorBg, gradientBg, customBg, videoBg, or transparentBase: true
videoBg still-frame controlsImage-style paritySupports inherit, fit, align, filters, opacity, 1-based frame or time, jpg/png and FFmpeg quality 1–31
opacity0 through 1Values outside the range are invalid
zoom.scaleGreater than 0Required when zoom is configured
bgLayersValidated per entrySupports configured color, gradient, image, pattern, preset-pattern, and noise layers
When you need a predictable banner or card sizeUse explicit width and height

the output dimensions remain independent of source-asset dimensions

When an image should determine canvas sizeUse customBg.inherit

the loaded image supplies effective dimensions

When a selected video frame should determine canvas sizeUse videoBg.inherit

the extracted still frame supplies effective dimensions and then uses the same fit/align/filter/opacity pipeline as customBg

When you need layered compositionUse bgLayers

layers make paint order explicit instead of overloading the primary fill

Paint architecture

SOURCEtext
text
CanvasConfig → validation → surface allocation → backgrounds/layers → clip and transforms → shadow/stroke → PNG buffer
High-level createCanvas pipeline
Primary fill rule

Use only one primary background among colorBg, gradientBg, customBg, videoBg, and transparentBase: true. videoBg extracts one still frame and then shares the same image-style inherit / fit / align / filters / opacity behavior as customBg. Additional layering concerns belong in the dedicated background-layer options.

Verified executable example

Executable example · minimal

Create a deterministic canvas

Render a fixed 320×180 server-side PNG using the public ApexPainter canvas API.

✓ VerifiedRuntime: nodeapexify.js

Prerequisites

  • Node.js 22, 24, or 26
  • apexify.js 6.0.0

Authoritative source

SOURCEtypescript
typescript
Studio
import { mkdir, writeFile } from 'node:fs/promises';import { join } from 'node:path';import { ApexPainter } from 'apexify.js'; const outputDir = process.env.APEXIFY_EXAMPLE_OUTPUT_DIR;if (!outputDir) throw new Error('APEXIFY_EXAMPLE_OUTPUT_DIR is required.'); const painter = new ApexPainter({ type: 'buffer' });const canvas = await painter.createCanvas({ width: 320, height: 180, colorBg: '#0f172a' });if (!Buffer.isBuffer(canvas.buffer)) throw new Error('Expected createCanvas() to expose a PNG Buffer.'); await mkdir(outputDir, { recursive: true });await writeFile(join(outputDir, 'canvas-basic.png'), canvas.buffer);console.log(JSON.stringify({ example: 'node.canvas.basic', format: 'png', width: 320, height: 180, bytes: canvas.buffer.length }));

Source hash: d1603f74395a1b3c07efbf96be39ca6d867413977a29ea556c0bfc1e712649e4. The displayed payload is generated from the files executed by DOC-5 verification.

Verified output · canvas-basic.png
Create a deterministic canvas verified output
320 × 180 · metadata verification

Goal

Create the smallest useful server-rendered image with explicit dimensions and background color.

Important options

  • width
  • height
  • colorBg

Why these choices

  • Explicit dimensions make output verification deterministic.
  • A local color background avoids remote assets and font dependencies.

Variants

  • Replace colorBg with a gradient or layered background after the basic pipeline is understood.

Performance note

The example uses one small canvas and performs no remote I/O.

Error note

Invalid dimensions are rejected by Apexify.js runtime validation before rendering.

Related documentation

Related API

Next steps

Use node.chart.bar for a generated chart or node.integration.report for a multi-file workflow.

What happens next

  1. The source above is read from the authoritative example file, not copied into this MDX page.
  2. DOC-5 installs the packed Apexify.js artifact into an isolated consumer fixture.
  3. The source typechecks, executes, and produces the preview shown above.
  4. Gallery consumes the same stable example identity and generated source/output record.

Implementation path

CanvasCreator.createCanvas (canvas/canvas-creator.ts) delegates through the canvas composition/paint helpers and supporting background, pattern, shadow, stroke, and clip-path modules.

Next steps

  • Continue to Canvas size and coordinates.
  • Open the canonical executable example page for source, verification state, output, and API relationships.
  • Use the legacy feature-guide links for deeper background/effect topics until DOC-9 migrates the remaining corpus to canonical routes.

Interactive example

Create a deterministic canvas

Open the verified source and output side by side. The editor is deferred until requested; this documentation surface does not pretend to run Node code in the browser.

Create a deterministic canvas verified output

Next steps

Canvas size and coordinatesGuide · node · CURRENT

Reference the width, height, x, and y sizing and coordinate behavior used by Apexify.js createCanvas.

Getting StartedGuide · node · CURRENT

Install the staged Apexify.js 6.0.0 package, understand its Node/server requirements, and render a first image.

Primary backgrounds (pick exactly one)Guide · node · CURRENT

Current Apexify.js 6.0.0 documentation for Primary backgrounds (pick exactly one).

Transparent base (transparentBase)Guide · node · CURRENT

Current Apexify.js 6.0.0 documentation for Transparent base (transparentBase).