Browser Setup

Grafex renders compositions using a headless WebKit browser powered by Playwright. Most of the time, this is handled for you automatically.

Automatic Installation

When you run npm install grafex, a postinstall script downloads the WebKit binary. No action needed.

bash

npm install grafex
# WebKit is downloaded automatically

The binary is cached — subsequent installs skip the download.

Manual Installation

If the postinstall script fails (corporate proxies, restricted environments), install WebKit manually:

bash

npx playwright install webkit

Or install only the browser binary without system dependencies:

bash

npx playwright-core install webkit

Chromium (Alternative Engine)

Grafex uses WebKit by default. Chromium is also supported if you hit CSS compatibility issues or need Chromium-specific rendering behavior. It requires a separate install:

bash

npx playwright install chromium

Then pass --browser chromium to the CLI:

bash

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

Or set browser: 'chromium' in the library API:

node

const result = await render('./card.tsx', {
  browser: 'chromium',
});

Note: WebKit is recommended for most use cases — it is smaller (~2 MB vs ~200 MB for Chromium) and downloaded automatically. Use Chromium only if you need specific rendering behavior that differs between engines.

`PLAYWRIGHT_BROWSERS_PATH`

By default, Playwright stores browser binaries in a shared cache directory under your home folder. Set PLAYWRIGHT_BROWSERS_PATH to change this location:

bash

export PLAYWRIGHT_BROWSERS_PATH=/path/to/browsers
npx playwright install webkit
grafex export -f card.tsx -o card.png

This is useful in CI environments where the home directory is read-only or ephemeral.

CI Setup

On Linux, WebKit requires system-level dependencies (GTK, GStreamer, etc.). Install them before the browser binary:

bash

npx playwright install-deps webkit
npx playwright install webkit

GitHub Actions

.github/workflows/images.yml

steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: 20

  - name: Install dependencies
    run: npm ci

  - name: Install WebKit system 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

Info: This pattern works in any CI environment that supports Node.js 20+. Adjust the dependency installation step for your platform (e.g., apt-get on Debian, yum on CentOS).

Troubleshooting

"Browser not found" error

WebKit was not downloaded. Run:

npx playwright install webkit

"Missing system dependencies" error (Linux)

WebKit needs system libraries that are not installed. Run:

npx playwright install-deps webkit

Then retry your export.

Slow first render

The first render takes longer because Grafex launches a new WebKit instance. Subsequent renders reuse the browser and are significantly faster (5-50ms). If you are rendering multiple images, use the library API to batch them with a single render() loop and one close() at the end.

Disk space concerns

The WebKit binary is approximately 2 MB (compressed). It is cached after the first download. Compare this to Puppeteer's Chromium at 200 MB+.