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 dev command starts a local HTTP server that renders your composition in a headless browser and serves the result as a live-updating preview. Every time you save the composition file, one of its imports, a referenced CSS file, or a local image asset, the server re-renders and pushes the updated image to the browser via Server-Sent Events — no manual refresh needed. Open http://localhost:3000 (or a custom port) to see your composition as it would look when exported.

​
Usage

grafex dev --file <path> [options]

​
Flags

​
--file
string
required
Path to the .tsx composition file to preview. Short form: -f.
​
--port
number
default:"3000"
Port for the local preview server. Must be an integer between 1 and 65535.
​
--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}'
​
--variant
string
Pin the preview to a specific named variant defined in config.variants. When omitted and the composition has variants, the preview defaults to the first variant in the config.variants object. The variant switcher UI in the browser is still available to switch between variants at runtime unless this flag is set.
​
--help
boolean
Print the help text and exit. Short form: -h.

​
Examples

grafex dev -f card.tsx

​
How the dev server works

1

Start the server and open a browser

grafex dev starts the HTTP server, performs an initial render, and automatically opens http://localhost:<port> in your default browser. The terminal prints a banner with the file name, port, composition dimensions, and initial render time.
  grafex dev  v1.0.0

  file     card.tsx
  url      http://localhost:3000
  size     1200 × 630 @ 1x
  time     142ms
2

Edit your composition

Save any watched file and the server re-renders within ~100ms. The browser updates automatically — no reload, no manual action. The terminal logs each change:
↺  card.tsx          189ms
↺  styles.css         74ms
3

Switch variants in the browser (when applicable)

When your composition defines config.variants, a variant switcher dropdown appears in the preview UI. Selecting a different variant triggers an immediate re-render for that variant. The URL updates to /?variant=<name> so you can bookmark or share the link.
4

Stop the server

Press Ctrl+C in the terminal. The server shuts down cleanly and the browser process is released.

​
File watching

The dev server watches the following files for changes:
File typeWhat is watched
CompositionThe .tsx file passed to --file
ImportsEvery local module imported by the composition (resolved at transpile time)
CSS filesFiles listed in config.css, resolved relative to the composition
Local image assetssrc attributes and CSS url() references that point to local files
All changes are debounced with a ~100ms delay. If you save a file multiple times in quick succession, only one render is triggered after the last save — preventing redundant work during fast edits.
If a CSS file listed in config.css does not exist yet when the server starts, Grafex renders without it and watches the parent directory. As soon as the file is created (e.g. by Tailwind’s --watch mode), Grafex detects it and re-renders automatically — no restart needed.

​
Variant switcher UI

When config.variants is defined, the preview page renders a dropdown above the composition image: 
Variant:  [ og ▾ ]
Selecting a variant immediately re-renders that variant and updates the preview. The selected variant is reflected in the URL (/?variant=twitter) so refreshing the page or sharing the link preserves the selection.
When --variant is passed on the command line, the variant is pinned for the entire session. The dropdown still appears in the browser but switching it triggers a fresh render for the requested variant.

​
Tailwind CSS workflow

Run Tailwind’s --watch mode alongside grafex dev for a fully live styling workflow: 
# Terminal 1 — Tailwind watcher
npx @tailwindcss/cli -i ./input.css -o ./styles.css --watch

# Terminal 2 — Grafex dev server
npx grafex dev -f card.tsx
Or run both in parallel with a single command using concurrently: 
{
  "scripts": {
    "dev": "concurrently \"npx @tailwindcss/cli -i ./input.css -o ./styles.css --watch\" \"npx grafex dev -f card.tsx\""
  }
}
When Tailwind rewrites styles.css, Grafex detects the CSS change and re-renders within ~100ms — no plugins or extra configuration needed.

​
Error overlay

If the composition throws an error during render (syntax error, runtime exception, missing module), the preview page shows a full-screen error overlay with the error message instead of crashing the server. Fix the error in your editor, save, and the overlay disappears as soon as the next render succeeds.
The dev server renders compositions using the same headless WebKit browser as grafex export. If your composition relies on browser APIs not available in WebKit, you may see errors in grafex dev that do not appear in a standard browser. The grafex dev command always uses WebKit; to test with Chromium, use grafex export --browser chromium instead.

​
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