Library API

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

TypeScript

import { render, close } from 'grafex';

`render(compositionPath, options?)`

Render a composition to a PNG 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.browser`	`'webkit'`	Browser engine (default: 'webkit')

Return value

render() returns a Promise<RenderResult>:

interface RenderResult {
  buffer: Buffer;   // PNG image data
  width: number;    // Effective render width
  height: number;   // Effective render height
  format: 'png';    // Output format
}

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();

`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 PNG
`BrowserManager`	Direct access to the browser lifecycle for custom workflows

Types

CompositionConfig

TypeScript

interface CompositionConfig {
  width?: number;    // Image width in pixels (default: 1200)
  height?: number;   // Image height in pixels (default: 630)
  format?: 'png';    // Output format (only PNG supported)
  fonts?: string[];  // URLs to load (e.g., Google Fonts)
}

RenderResult

TypeScript

interface RenderResult {
  buffer: Buffer;   // PNG image data
  width: number;    // Effective render width
  height: number;   // Effective render height
  format: 'png';    // Output format
}

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
  browser?: 'webkit';               // Browser engine
}