Use this file to discover all available pages before exploring further.
render() is the primary entry point for programmatic image generation in Grafex. It accepts a path to a .tsx composition file, transpiles and executes the file in Node.js, loads the resulting HTML into a headless browser, and returns a buffer containing the final image. The browser instance is created on the first call and reused for all subsequent calls within the same process, so there is no per-call launch overhead after the first render.
Optional configuration object. All fields override the values in the composition’s config export. If a field is not provided, the value from config (or the named variant’s config) is used; if neither is set, the documented default applies.
Props to pass to the default-exported component. These are shallow-merged on top of any props defined in config.variants[variant] — per-call props win on a key-by-key basis.
Override the composition width in pixels. Takes precedence over the variant config, which takes precedence over the base config.width. Defaults to 1200 if not set anywhere.
Override the composition height in pixels. Takes precedence over the variant config, which takes precedence over the base config.height. Defaults to 630 if not set anywhere.
Device pixel ratio. Set to 2 to produce a high-DPI (retina) image: a 1200×630 composition with scale: 2 renders as a 2400×1260 pixel image. The width and height in RenderResult reflect the scaled pixel dimensions.
Browser engine used for rendering. WebKit is the default and is installed automatically with the package. Pass 'chromium' if you need different CSS rendering behaviour — Chromium must be installed separately via npx playwright install chromium.
Name of a variant defined in config.variants to render. The variant’s width, height, scale, format, quality, props, fonts, css, and htmlAttributes are applied before any per-call overrides. Throws if the composition has no variants defined, or if the named variant does not exist.
import { render, close } from 'grafex';import { writeFile } from 'node:fs/promises';try { const result = await render('./card.tsx'); await writeFile('./card.png', result.buffer); console.log(`Saved ${result.width}×${result.height} ${result.format}`);} finally { await close();}
Option values set in the call always override the composition’s config export. The resolution order is: call options → variant config → base config → built-in default.
Passing variant when the composition has no config.variants defined throws an error. Check first with getCompositionConfig + hasVariants if variant presence is uncertain at call time.
