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.

Grafex uses a headless WebKit browser under the hood. On macOS and Windows the browser binary ships with all its dependencies, but on Linux — where most CI runners operate — additional system libraries must be installed separately. This guide walks through the exact steps for GitHub Actions and covers caching, alternative engines, and containerized environments.

​
GitHub Actions setup

1

Install Node.js and Grafex

Make sure your workflow includes a Node.js setup step and installs your project dependencies. Grafex’s postinstall script downloads the WebKit binary automatically.
- name: Set up Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'

- name: Install dependencies
  run: npm install
2

Install WebKit system dependencies

On Linux runners, WebKit requires OS-level libraries (GTK, glib, and others). Install them with Playwright’s install-deps command. This must run before the browser itself is installed.
npx playwright install-deps webkit
3

Install the WebKit browser binary

Download the WebKit binary that Playwright manages. This is the same binary Grafex uses at render time.
npx playwright install webkit
4

Export your composition

With the browser in place, run grafex export as you would locally.
npx grafex export -f card.tsx -o card.png

​
Complete GitHub Actions workflow

Below is a ready-to-use workflow file. Copy it into .github/workflows/export.yml and adjust the file paths to match your project. 
name: Export images

on:
  push:
    branches: [main]

jobs:
  export:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm install

      - name: Install WebKit dependencies
        run: npx playwright install-deps webkit

      - name: Install WebKit
        run: npx playwright install webkit

      - name: Export image
        run: npx grafex export -f card.tsx -o card.png
To cache the WebKit binary between workflow runs, set the PLAYWRIGHT_BROWSERS_PATH environment variable to a directory inside your workspace and include it in an actions/cache step. This avoids re-downloading the binary on every run, which can save 30–60 seconds depending on runner speed.
- name: Cache WebKit
  uses: actions/cache@v4
  with:
    path: .browsers
    key: webkit-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

- name: Install WebKit
  run: npx playwright install webkit
  env:
    PLAYWRIGHT_BROWSERS_PATH: .browsers
Any subsequent Grafex commands in the same job will also pick up PLAYWRIGHT_BROWSERS_PATH if it is set in the job environment.

​
PLAYWRIGHT_BROWSERS_PATH

By default, Playwright installs browser binaries to a shared cache directory that may not be writable in all CI environments. Set PLAYWRIGHT_BROWSERS_PATH to any writable path to override the location: 
export PLAYWRIGHT_BROWSERS_PATH=/path/to/browsers
npx playwright install webkit
npx grafex export -f card.tsx -o card.png
Grafex inherits this environment variable automatically — no extra configuration needed.

​
Chromium as an alternative engine

If you encounter WebKit-specific CSS compatibility issues, Grafex also supports Chromium. Install it the same way and pass --browser chromium to the CLI. 
npx playwright install-deps chromium
npx playwright install chromium
npx grafex export -f card.tsx -o card.png --browser chromium
WebKit and Chromium may render certain CSS properties — subpixel fonts, blur filters, gradients — slightly differently. Test your compositions with both engines if you switch, and make sure any visual regression checks account for the engine in use.

​
Docker and containerized environments

The same dependency installation steps apply inside Docker containers. Add the following to your Dockerfile or container setup script before running Grafex: 
npx playwright install-deps webkit
npx playwright install webkit
If the container runs as a non-root user whose home directory is not writable, set PLAYWRIGHT_BROWSERS_PATH to a directory the user owns before running playwright install: 
export PLAYWRIGHT_BROWSERS_PATH=/app/.browsers
npx playwright install webkit

Build docs developers (and LLMs) love

Get started for freeTalk to us