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 export command renders a composition file to an image on disk. It launches a headless browser, loads your JSX/TSX composition, and captures the result as a PNG or JPEG. For compositions that define multiple variants, a single invocation renders every variant and writes each output to a named file — no shell loop required.

​
Usage

grafex export --file <path> [options]

​
Flags

​
--file
string
required
Path to the .tsx composition file to render. Short form: -f.
​
--out
string
default:"./output.png"
Output file path or directory. Short form: -o.
  • For a single-variant composition, this is the path to the output file (e.g. ./card.png). Defaults to ./output.png.
  • For a multi-variant composition, this must be a directory path (e.g. ./images/). Defaults to ./. Each variant is written as <variant-name>.<format> inside that directory. Passing a single file path with multiple variants is an error.
​
--props
string (JSON)
default:"{}"
Props to pass to the composition’s default export, serialised as a JSON string. The string must be valid JSON.
--props '{"title":"Hello World","dark":true}'
​
--width
number
Override the composition width in pixels, ignoring the width set in config. Must be an integer.
​
--height
number
Override the composition height in pixels, ignoring the height set in config. Must be an integer.
​
--format
string
default:"png"
Output image format. Accepted values: png, jpeg. The alias jpg is also accepted and treated identically to jpeg.
​
--quality
number
default:"90"
JPEG compression quality, from 1 (lowest) to 100 (highest). Has no effect when --format is png — a warning is printed if you combine the two.
​
--scale
number
default:"1"
Device pixel ratio. Set to 2 to produce a retina / high-DPI image: a 1200 × 630 composition with --scale 2 writes a 2400 × 1260 pixel file while preserving the logical layout at 1200 × 630.
​
--browser
string
default:"webkit"
Browser engine to use for rendering. Accepted values: webkit, chromium. Chromium must be installed separately (npx playwright install chromium) before it can be used.
​
--variant
string
Render only the named variant defined in config.variants. When omitted, all variants are rendered. Has no effect on compositions that do not define variants.
​
--help
boolean
Print the help text and exit. Short form: -h.

​
Examples

grafex export -f card.tsx -o card.png

​
Multi-variant behaviour

When a composition exports a config.variants object, grafex export renders every variant in a single pass unless --variant is specified. 
# Given config.variants = { og: {}, twitter: { height: 675 }, square: { width: 1080, height: 1080 } }

grafex export -f card.tsx
# Writes: ./og.png  ./twitter.png  ./square.png

grafex export -f card.tsx -o ./dist/
# Writes: ./dist/og.png  ./dist/twitter.png  ./dist/square.png
Each line of stdout is the path of one written file, so the output is easy to pipe into other tools: 
./dist/og.png
./dist/twitter.png
./dist/square.png
Passing a single file path (e.g. -o card.png) when the composition has multiple variants is an error:
Error: Cannot use a single output file with multiple variants. Use a directory path or --variant.
Use a directory path ending in / or pass --variant to select one.
The output directory is created automatically with mkdirSync({ recursive: true }) if it does not exist — you do not need to mkdir it first.

​
Format and quality notes

Format--quality effectRecommended use
pngNone (warning printed if set)Lossless output, screenshots, images with transparency
jpegControls compression, 1–100, default 90Photos, large backgrounds, smaller file sizes
jpg is accepted as an alias for jpeg in --format — the output file extension and MIME type are always jpeg regardless of which alias you use.

​
Global flags

The following flags are available on the top-level grafex command, before any subcommand: 
grafex --version    # Print the installed Grafex version and exit
grafex --help       # Print top-level help text and exit

Build docs developers (and LLMs) love

Get started for freeTalk to us