Composition Config Fields: Complete Reference Guide

Every Grafex composition exports a config object typed as CompositionConfig. This object is the single source of truth for how your composition is sized, styled, and rendered. You can define it once and override individual fields from the CLI or the Node.js API without touching the file. All fields are optional — Grafex falls back to sensible defaults when a field is omitted.

CompositionConfig fields

width

number

Composition width in pixels. Defaults to 1200 when not set in config, CLI, or API options.

export const config: CompositionConfig = {
  width: 1200,
};

height

number

Composition height in pixels. Defaults to 630 when not set in config, CLI, or API options.

export const config: CompositionConfig = {
  height: 630,
};

scale

number

Device pixel ratio for high-DPI output. A 1200×630 composition with scale: 2 produces a 2400×1260 image — same layout, double the pixel density. Defaults to 1.

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

Use scale: 2 to produce retina-ready images without changing your CSS dimensions. All layout values in your JSX stay the same; only the output resolution doubles.

format

'png' | 'jpeg'

Default output format. Defaults to 'png'. The CLI --format flag and the API format option override this value.

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  format: 'jpeg',
};

quality

number

JPEG compression quality, from 1 (lowest) to 100 (highest). Only applies when format is 'jpeg'. Defaults to 90 when not specified and the format is JPEG.

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  format: 'jpeg',
  quality: 85,
};

fonts

string[]

CSS stylesheet URLs to load as fonts before rendering. Each entry is injected as a <link rel="stylesheet"> tag in the HTML <head>, so Google Fonts URLs and any other CSS-serving endpoint work directly. Local file paths are not supported in this field — use config.css with @font-face rules for self-hosted fonts instead.

export const config: CompositionConfig = {
  width: 800,
  height: 400,
  fonts: ['https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap'],
};

See Fonts for full details.

css

string[]

Paths to CSS files to inject into the page before rendering. Paths are resolved relative to the composition file. Each file’s contents are injected as a <style> tag in the HTML <head>.

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

See CSS Files for full details.

variants

Record<string, VariantConfig>

Named output variants. Each key becomes a variant name, and each value is a VariantConfig that can override any base config field. When variants are defined, grafex export renders all of them by default, naming each output file after its variant key.

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

See Variants for full details including merge rules.

htmlAttributes

Record<string, string>

Attributes to set on the root <html> element. Values are HTML-escaped automatically. This is useful for CSS selectors that target the <html> element, such as :root[data-theme="dark"] used by Tailwind v4 and other theming systems.

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  htmlAttributes: {
    'data-theme': 'dark',
    lang: 'en',
  },
};

This renders as <html data-theme="dark" lang="en">. When a variant also defines htmlAttributes, the variant’s attributes are spread over the base config’s attributes — see Variants for the full merge rules.

Complete example

The composition below combines every config field into a single file. It sets base dimensions and format, loads a custom font and a Tailwind CSS stylesheet, sets data-theme on the HTML element for dark-mode theming, and defines three output variants.

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

export const config: CompositionConfig = {
  width: 1200,
  height: 630,
  scale: 2,
  format: 'png',
  fonts: ['https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap'],
  css: ['./styles.css'],
  htmlAttributes: {
    'data-theme': 'dark',
    lang: 'en',
  },
  variants: {
    og: {},
    twitter: { height: 675 },
    square: { width: 1080, height: 1080, props: { layout: 'square' } },
  },
};

export default function Card({ layout = 'default' }: { layout?: string }) {
  return (
    <div
      style={{
        width: '100%',
        height: '100%',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        fontFamily: 'Inter, system-ui, sans-serif',
      }}
    >
      {layout}
    </div>
  );
}

Overriding config at export time

Any field set in config can be overridden from the CLI without editing the file:

# Override dimensions and format
grafex export -f card.tsx -o card.png --width 800 --height 400 --format jpeg --quality 80

# Override scale for a standard-DPI build
grafex export -f card.tsx -o card.png --scale 1

The same overrides are available in the Node.js API:

import { render, close } from 'grafex';

const result = await render('./card.tsx', {
  width: 800,
  height: 400,
  format: 'jpeg',
  quality: 80,
});

await close();

CLI and API options sit at the top of the override chain: they beat variant config, which beats base config. The priority order is always CLI/API → variant → base config → defaults.

Get Started

Compositions

Guides

Composition Config Fields: Complete Reference Guide