Library API

Use Grafex programmatically in your Node.js applications. Useful for build scripts, CI pipelines, and server-side image generation.

typescript

import { render, renderAll, close } from 'grafex';

`render(compositionPath, options?)`

Render a composition to an image buffer.

typescript

const result = await render('./card.tsx', {
  props: { title: 'Hello' },
  width: 1200,
  height: 630,
});

Parameters

Parameter	Type	Description
`compositionPath`	`string`	Path to the .tsx composition file
`options.props`	`Record<string, unknown>`	Props to pass to the composition
`options.width`	`number`	Override composition width in pixels
`options.height`	`number`	Override composition height in pixels
`options.format`	`'png' \| 'jpeg'`	Output format (default: 'png')
`options.quality`	`number`	JPEG quality 1–100 (default: 90, only applies when format is jpeg)
`options.browser`	`'webkit' \| 'chromium'`	Browser engine (default: 'webkit')
`options.scale`	`number`	Device pixel ratio (default: 1)
`options.variant`	`string`	Named variant to render from config.variants

Return value

render() returns a Promise<RenderResult>:

interface RenderResult {
  buffer: Buffer;          // Image data
  width: number;           // Effective render width (after scaling)
  height: number;          // Effective render height (after scaling)
  format: 'png' | 'jpeg';  // Output format
  scale: number;           // Device pixel ratio used
}

Example — write to file

typescript

import { render, close } from 'grafex';
import { writeFileSync } from 'node:fs';

const result = await render('./card.tsx', {
  props: { title: 'Hello World' },
});

writeFileSync('card.png', result.buffer);
await close();

`renderAll(compositionPath, options?)`

Render all variants defined in config.variants. Returns a Map<string, RenderResult> keyed by variant name. Throws if the composition has no variants defined.

typescript

const all = await renderAll('./card.tsx', {
  props: { title: 'Hello' },
});

for (const [name, result] of all) {
  writeFileSync(`${name}.${result.format}`, result.buffer);
}

Accepts the same options as render(), except variant is ignored — all variants are always rendered.

`close()`

Shut down the browser process. Call this when you are done rendering to free resources.

await close();

Caution: Always call close() when finished. Leaving the browser process running will leak memory and prevent your Node.js process from exiting cleanly.

Example — render multiple compositions

typescript

const pages = [
  { file: 'hero.tsx', out: 'hero.png' },
  { file: 'card.tsx', out: 'card.png' },
  { file: 'thumbnail.tsx', out: 'thumbnail.png' },
];

for (const page of pages) {
  const result = await render(page.file);
  writeFileSync(page.out, result.buffer);
}

await close();

Advanced Exports

For lower-level control, Grafex exposes additional internals:

typescript

import { h, Fragment, renderToHTML, BrowserManager } from 'grafex';

Export	Description
`h`	JSX factory function
`Fragment`	JSX fragment implementation
`renderToHTML`	Convert a composition to an HTML string without rendering to an image
`BrowserManager`	Direct access to the browser lifecycle for custom workflows

Types

VariantConfig

typescript

interface VariantConfig {
  width?: number;
  height?: number;
  scale?: number;
  format?: 'png' | 'jpeg';
  quality?: number;
  fonts?: string[];
  css?: string[];
  props?: Record<string, unknown>; // Props injected for this variant
  htmlAttributes?: Record<string, string>; // Attributes on <html> (spread over base config)
}

CompositionConfig

typescript

interface CompositionConfig {
  width?: number;           // Image width in pixels (default: 1200)
  height?: number;          // Image height in pixels (default: 630)
  format?: 'png' | 'jpeg';  // Output format (default: 'png')
  quality?: number;         // JPEG quality 1-100 (default: 90)
  fonts?: string[];         // URLs to font stylesheets
  css?: string[];           // CSS file paths to inject
  scale?: number;           // Device pixel ratio (default: 1)
  variants?: Record<string, VariantConfig>; // Named output variants
  htmlAttributes?: Record<string, string>;  // Attributes set on the root <html> element
}

RenderResult

typescript

interface RenderResult {
  buffer: Buffer;           // Image data
  width: number;            // Effective render width (after scaling)
  height: number;           // Effective render height (after scaling)
  format: 'png' | 'jpeg';   // Output format
  scale: number;            // Device pixel ratio used
}

RenderOptions

typescript

interface RenderOptions {
  props?: Record<string, unknown>;    // Props passed to the composition
  width?: number;                     // Override width in pixels
  height?: number;                    // Override height in pixels
  format?: 'png' | 'jpeg';            // Output format (default: 'png')
  quality?: number;                   // JPEG quality 1-100 (default: 90)
  browser?: 'webkit' | 'chromium';    // Browser engine (default: 'webkit')
  scale?: number;                     // Device pixel ratio (default: 1)
  variant?: string;                   // Named variant to render
}