Grafex is a programmatic image composition tool that lets you write image layouts in JSX/TSX and export them as PNG or JPEG files. Instead of reaching for a design tool or fighting a canvas API, you describe your image the same way you describe a UI component — with markup, inline styles, and CSS — then hand it to the CLI or Node.js API and get a pixel-perfect image back.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.
How it works
Every export passes through a four-stage rendering pipeline:- Transpile — esbuild compiles your
.tsxfile, injecting Grafex’s customhandFragmentJSX runtime functions at build time. No React, no external dependencies in your composition file. - Execute — the transpiled module is evaluated in Node.js. Your default-export component function is called to produce an HTML string.
- Render — the HTML string is wrapped in a full
<!DOCTYPE html>document and loaded into a headless WebKit browser page sized to yourconfig.widthandconfig.height. - Screenshot — Playwright captures a screenshot of the page and returns it as a
Bufferin PNG or JPEG format.
Key capabilities
CLI & Node.js API
Export images from the command line with
npx grafex export, or call render() and renderAll() programmatically from any Node.js script or build pipeline.Variants
Define multiple named variants in a single composition — different sizes, formats, or props — and export them all in one pass or target a specific one.
Full CSS support
Load external
.css files via config.css. Works with plain stylesheets, Tailwind output, or any compiled CSS — injected as <style> tags before rendering.Local images
Reference local PNG, JPEG, WebP, SVG, and other image formats in
<img> tags or CSS background-image. Grafex embeds them as base64 data URLs automatically.Live dev server
Run
npx grafex dev -f composition.tsx to open a preview that updates within ~100ms whenever you save the composition, its imports, or any watched CSS file.High-DPI output
Set
scale: 2 in the config, CLI, or API to produce retina-density images. A 1200×630 composition at scale: 2 outputs a 2400×1260 PNG with the same layout.Requirements
Grafex requires Node.js >= 20.0.0. WebKit is the default rendering engine and is downloaded automatically when you runnpm install grafex via a postinstall script — no manual browser setup needed on macOS or Windows.
On Linux (including CI), WebKit requires system dependencies that must be installed separately:
npx playwright install chromium and pass --browser chromium to the CLI or browser: 'chromium' to the API.
Next steps
Follow the quickstart to go from zero to a working exported image in under two minutes.Quickstart
Install Grafex, scaffold a starter composition, and export your first image.