CompositionConfig: Configure Your Grafex Composition

The CompositionConfig interface is the primary way to declare the output settings for a composition. Export a config constant from your .tsx file and Grafex reads it before rendering — no CLI flags required for the common case. Every field is optional, so you can start with just width and height and add more as your needs grow.

import type { CompositionConfig, VariantConfig } from 'grafex'

CompositionConfig

interface CompositionConfig {
  width?: number;
  height?: number;
  scale?: number;
  format?: 'png' | 'jpeg';
  quality?: number;
  fonts?: string[];
  css?: string[];
  variants?: Record<string, VariantConfig>;
  htmlAttributes?: Record<string, string>;
}

width

number

Width of the composition viewport in logical pixels. Used as the browser viewport width before any scale factor is applied. Typically set to the desired output width — for example, 1200 for an Open Graph image.

height

number

Height of the composition viewport in logical pixels. Typically set to the desired output height — for example, 630 for an Open Graph image.

scale

number

default:"1"

Device pixel ratio applied to the viewport. A value of 2 produces retina-quality output: a 1200×630 composition at scale: 2 renders a 2400×1260 physical-pixel image while the layout still sees a 1200×630 viewport. The physical pixel dimensions equal width × scale and height × scale.

format

'png' | 'jpeg'

default:"'png'"

Image format for the exported file. Use 'jpeg' for photographs or compositions with complex gradients where a smaller file size is acceptable. Use 'png' (the default) for compositions that require transparency or crisp text.

quality

number

default:"90"

JPEG compression quality on a scale from 1 (smallest file, lowest quality) to 100 (largest file, highest quality). Only applied when format is 'jpeg' — this field has no effect on PNG output.

fonts

string[]

Paths to local font files (.ttf, .otf, .woff, .woff2) to load before rendering. Paths are resolved relative to the composition file. Fonts loaded here are available to all CSS font-family declarations in the composition.

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  fonts: ['./fonts/Inter-Regular.ttf', './fonts/Inter-Bold.ttf'],
};

css

string[]

Paths to external CSS files to inject into the page <head> before rendering. Paths are resolved relative to the composition file. This field accepts any CSS — plain stylesheets, Tailwind output, Sass output, or any other generated .css file.

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  css: ['./styles.css'],
};

Array fields like css and fonts replace the base config value when a variant overrides them — they do not merge. If a variant specifies css: ['./dark.css'], only dark.css is loaded for that variant.

variants

Record<string, VariantConfig>

A named map of variant configurations. Each key becomes the variant name and each value is a VariantConfig that inherits all base config fields, then overrides only the ones you specify. When variants are defined, the CLI renders all of them by default and names the output files after the variant keys.

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  variants: {
    og:      {},
    twitter: { height: 675 },
    square:  { width: 1080, height: 1080, props: { layout: 'square' } },
  },
};

Show VariantConfig fields

Each entry in variants is a VariantConfig. It has the same dimension, format, font, and CSS fields as CompositionConfig — but no nested variants — plus a props field to pass data to the composition component.

width

number

Override the base config width for this variant only.

height

number

Override the base config height for this variant only.

scale

number

Override the device pixel ratio for this variant only.

format

'png' | 'jpeg'

Override the output format for this variant only.

quality

number

Override the JPEG quality (1–100) for this variant only. Only applies when format is 'jpeg'.

fonts

string[]

Replace the base config fonts list for this variant. Paths are resolved relative to the composition file.

css

string[]

Replace the base config css list for this variant. Paths are resolved relative to the composition file.

props

Record<string, unknown>

Props to pass to the composition’s default-export component for this variant. These are shallow-merged with any props passed via the CLI (--props) or the library API (options.props) — CLI/API props take precedence over variant props for overlapping keys.

variants: {
  square: { width: 1080, height: 1080, props: { layout: 'square' } },
}

htmlAttributes

Record<string, string>

HTML attributes to set on the root <html> element for this variant. The variant’s attributes are spread over the base config’s htmlAttributes — keys present in both are overridden by the variant value, and keys present only in the base are preserved.

// Base sets data-theme="light"; dark variant overrides it
variants: {
  light: {},
  dark:  { htmlAttributes: { 'data-theme': 'dark' } },
}

htmlAttributes

Record<string, string>

Arbitrary attributes to set on the root <html> element. Attribute values are HTML-escaped automatically. This is useful for theming systems that rely on CSS selectors like :root[data-theme="dark"], including Tailwind CSS v4.

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  htmlAttributes: {
    'data-theme': 'dark',
    lang: 'en',
  },
};
// Renders as: <html data-theme="dark" lang="en">

Merge precedence

When rendering with variants, CLI flags, or library API options, settings are resolved in this order (highest to lowest precedence):

CLI flags / RenderOptions passed to render() or renderAll()
The matching VariantConfig entry
The base CompositionConfig

props are shallow-merged across all three levels. css and fonts arrays replace the base value — they do not concatenate. htmlAttributes from a variant are spread over the base attributes.

Example

// card.tsx
import type { CompositionConfig } from 'grafex';

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  scale: 2,
  format: 'png',
  css: ['./styles.css'],
  fonts: ['./fonts/Inter-Regular.ttf'],
  htmlAttributes: { 'data-theme': 'light' },
  variants: {
    light: {},
    dark: {
      htmlAttributes: { 'data-theme': 'dark' },
      props: { theme: 'dark' },
    },
  },
};

export default function Card({ theme = 'light' }: { theme?: string }) {
  return (
    <div style={{ width: '100%', height: '100%' }}>
      {theme} card
    </div>
  );
}

# Renders light.png and dark.png at 2400×1260 physical pixels each
npx grafex export -f card.tsx -o ./dist/

CLI

Library API

Types

CompositionConfig: Configure Your Grafex Composition