Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/andresilva-cc/grafex/llms.txt

Use this file to discover all available pages before exploring further.

The Grafex library lets you drive image generation directly from Node.js code — no CLI invocation required. Import render to convert a composition to a buffer, renderAll to process every variant in one call, and close to shut down the shared browser process when you’re finished. The library manages a single headless WebKit (or Chromium) browser instance internally, so all render calls within a session share the same warm browser — no repeated launch overhead.

​
Installation

npm install grafex
WebKit is downloaded automatically during npm install via a postinstall script. No extra setup is needed.

​
Imports

The three core functions cover the full rendering lifecycle: 
import { render, renderAll, close } from 'grafex';
Advanced use cases — such as building a custom render pipeline or implementing your own browser manager — expose lower-level primitives: 
import { h, Fragment, renderToHTML, BrowserManager } from 'grafex';
Additional utility exports: 
import { getCompositionConfig, hasVariants } from 'grafex';
TypeScript types are re-exported directly from the package: 
import type {
  RenderOptions,
  RenderResult,
  CompositionConfig,
  VariantConfig,
  HtmlString,
} from 'grafex';

​
Browser lifecycle

Grafex creates one shared BrowserManager instance the first time render() or renderAll() is called. That browser process stays alive across all subsequent render calls in the same Node.js process, which avoids the cost of launching a new browser on every image. You are responsible for calling close() once you are done rendering. Without it, the browser process keeps the Node.js event loop open and your script will not exit cleanly. After close() is called, the internal reference is cleared. The next call to render() or renderAll() automatically creates a fresh browser instance, so there is no need to manually re-initialize anything.
Always call close() when you are done, ideally inside a try/finally block. If an error is thrown during rendering and close() is never reached, the browser process will leak and keep your script hanging.

​
Function reference

render()

Render a single composition — or one named variant — to a Buffer.

renderAll()

Render every variant defined in config.variants in a single call, returning a Map keyed by variant name.

close()

Shut down the shared browser process and free all resources when you’re done rendering.

​
Complete example

The script below renders three compositions sequentially, writes each output to disk, then closes the browser. A single browser instance is reused across all three render calls. 
import { render, close } from 'grafex';
import { writeFile } from 'node:fs/promises';

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

try {
  for (const { file, out } of compositions) {
    const result = await render(file, { scale: 2 });
    await writeFile(out, result.buffer);
    console.log(`Rendered ${out} — ${result.width}×${result.height} ${result.format}`);
  }
} finally {
  await close();
}
The try/finally pattern ensures close() always runs, even if one of the render calls throws an error mid-batch.

Build docs developers (and LLMs) love

Get started for freeTalk to us