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 automatically resolves and embeds local image files so you never need a running server or a public URL to include them in a composition. When the renderer encounters an <img> tag or a CSS url() reference that points to a local path, it reads the file from disk and replaces the path with a base64 data URL before the page is rendered. The rendered image is fully self-contained.

​
Using images in JSX

Reference local image files in <img> tags using paths relative to your composition file: 
// card.tsx
import type { CompositionConfig } from 'grafex';

export const config: CompositionConfig = {
  width: 800,
  height: 400,
};

export default function WithImage() {
  return (
    <div
      style={{
        width: '800px',
        height: '400px',
        backgroundColor: '#1e293b',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
      }}
    >
      <img src="./test-image.png" alt="test" width="100" height="100" />
    </div>
  );
}
The ./test-image.png path is resolved relative to card.tsx. If the file exists at that path, Grafex embeds it automatically — no additional configuration required.

​
Using images in CSS

CSS url() references are embedded the same way, whether they appear in inline style attributes or in external CSS files loaded via config.css. Inline style attribute: 
export default function Card() {
  return (
    <div
      style={{
        width: '1200px',
        height: '630px',
        backgroundImage: "url('./hero.jpg')",
        backgroundSize: 'cover',
        backgroundPosition: 'center',
      }}
    >
      Card content
    </div>
  );
}
External CSS file (via config.css): 
/* styles.css */
.hero {
  background-image: url('./hero.jpg');
  background-size: cover;
  background-position: center;
}

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

export default function Card() {
  return (
    <div className="hero" style={{ width: '1200px', height: '630px' }}>
      Card content
    </div>
  );
}
In both cases, ./hero.jpg is resolved relative to the file it appears in — the composition file for inline styles, and the CSS file for external stylesheets.

​
Supported formats

Grafex can embed any of the following image formats:
ExtensionMIME type
.pngimage/png
.jpg / .jpegimage/jpeg
.gifimage/gif
.webpimage/webp
.svgimage/svg+xml
.avifimage/avif
.icoimage/x-icon
.bmpimage/bmp

​
Remote URLs and data URLs

Remote URLs starting with http://, https://, or // are passed through unchanged — Grafex does not fetch or re-encode them. Data URLs (strings starting with data:) are also passed through as-is. 
export default function Card() {
  return (
    <div style={{ width: '1200px', height: '630px' }}>
      {/* Remote URL — passed through, fetched by the browser */}
      <img src="https://example.com/logo.png" alt="Remote logo" width="200" height="60" />

      {/* Local file — read from disk and embedded as base64 */}
      <img src="./local-logo.png" alt="Local logo" width="200" height="60" />
    </div>
  );
}
Grafex emits a warning to stderr if a local image file is larger than 5 MB. Very large assets increase render time and output file size. Consider resizing or compressing images before including them in compositions.
If a local image path cannot be resolved — because the file doesn’t exist or the path is wrong — Grafex throws an error with the full resolved path so you can diagnose the problem quickly.

Build docs developers (and LLMs) love

Get started for freeTalk to us