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 scale option controls the device pixel ratio that Grafex passes to the headless browser. Setting it to 2 tells the browser to render at double resolution: a composition declared as 1200×630 pixels produces a 2400×1260 PNG. The layout, font sizes, and spacing all stay exactly the same — only the raw pixel count changes, making every edge and glyph sharper on retina and high-DPI displays.

​
How scale works

When Grafex renders a composition, it opens a browser viewport at the composition’s logical dimensions (width × height) and takes a screenshot at the given device pixel ratio. With scale: 1 (the default), one logical pixel equals one image pixel. With scale: 2, every logical pixel maps to a 2×2 block of image pixels.
Composition configscaleOutput dimensions
1200 × 63011200 × 630 px
1200 × 63022400 × 1260 px
800 × 4001800 × 400 px
800 × 40032400 × 1200 px

​
Three ways to set scale

​
1. In the composition config

Embed scale directly in config so every export of that composition defaults to retina resolution without any extra flags. 
import type { CompositionConfig } from 'grafex';

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  scale: 2,
};

export default function Card() {
  return (
    <div
      style={{
        width: '100%',
        height: '100%',
        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        color: 'white',
        fontSize: '64px',
        fontWeight: 'bold',
        fontFamily: 'system-ui, sans-serif',
      }}
    >
      Hello, Grafex!
    </div>
  );
}

​
2. CLI flag

Override scale at export time without touching the composition file. This is handy when you want both a 1× and a 2× version from the same source. 
# Standard resolution — 1200 × 630 px
npx grafex export -f card.tsx -o card.png

# Retina resolution — 2400 × 1260 px, same layout
npx grafex export -f card.tsx -o card@2x.png --scale 2

​
3. Library API

Pass scale as a render option when using Grafex programmatically. 
import { render, close } from 'grafex';
import { writeFileSync } from 'node:fs';

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

// result.scale  → 2
// result.width  → 2400
// result.height → 1260

writeFileSync('card@2x.png', result.buffer);
await close();
The RenderResult.scale field always reflects the device pixel ratio that was used, whether it came from the composition config, the CLI, or the API option.

​
Scale in variants

Each variant can carry its own scale, allowing you to produce standard and retina outputs from a single grafex export run. 
import type { CompositionConfig } from 'grafex';

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  variants: {
    standard: {},
    retina: { scale: 2 },
  },
};

export default function Card() {
  return (
    <div
      style={{
        width: '100%',
        height: '100%',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        fontSize: '64px',
        fontFamily: 'system-ui, sans-serif',
      }}
    >
      Hello, Grafex!
    </div>
  );
}
Running grafex export -f card.tsx (no --variant flag) renders both variants and writes standard.png (1200×630) and retina.png (2400×1260) in one pass.
Use scale: 2 for Open Graph images shared on social media (Twitter/X, LinkedIn, Slack unfurls) and any image that appears on retina MacBooks or high-DPI monitors. The file will be larger, but platforms and browsers will display it at the correct logical size with noticeably crisper text and edges.

​
Before and after

The same 1200×630 composition rendered at scale 1 and scale 2 produces identical visual output, but at very different pixel counts:

Scale 1 — standard

Output: 1200 × 630 pxCorrect for standard-density screens and environments where file size matters. Appears blurry on retina displays when upscaled by the browser.

Scale 2 — retina

Output: 2400 × 1260 pxCrisp on retina and high-DPI screens. Recommended for OG images, social cards, and any image embedded in a web page that may be displayed on a high-DPI device.
scale is not the same as width and height. Changing width and height changes the logical layout of your composition. Changing scale only multiplies the pixel density — the layout remains identical to what you see at scale 1.

Build docs developers (and LLMs) love

Get started for freeTalk to us