json-render/packages/image

@json-render/image

Image renderer for @json-render/core. Generate SVG and PNG images from JSON specs using Satori.

Install

npm install @json-render/core @json-render/image

For PNG output, also install the optional peer dependency:

npm install @resvg/resvg-js

Quick Start

Render a spec to SVG

import { renderToSvg } from "@json-render/image/render";
import type { Spec } from "@json-render/core";

const spec: Spec = {
  root: "frame",
  elements: {
    frame: {
      type: "Frame",
      props: { width: 1200, height: 630, backgroundColor: "#1a1a2e" },
      children: ["heading", "subtitle"],
    },
    heading: {
      type: "Heading",
      props: { text: "Hello World", level: "h1", color: "#ffffff" },
      children: [],
    },
    subtitle: {
      type: "Text",
      props: { text: "Generated from JSON", fontSize: 24, color: "#a0a0b0" },
      children: [],
    },
  },
};

const svg = await renderToSvg(spec, {
  fonts: [
    {
      name: "Inter",
      data: await fetch("https://example.com/Inter-Regular.ttf").then((r) =>
        r.arrayBuffer()
      ),
      weight: 400,
      style: "normal",
    },
  ],
});

Render to PNG

import { renderToPng } from "@json-render/image/render";

const png = await renderToPng(spec, {
  fonts: [
    {
      name: "Inter",
      data: await readFile("./Inter-Regular.ttf"),
      weight: 400,
      style: "normal",
    },
  ],
});

// Write to file
await writeFile("output.png", png);

With a custom catalog

import { defineCatalog } from "@json-render/core";
import { schema, renderToSvg } from "@json-render/image";
import { standardComponentDefinitions } from "@json-render/image/catalog";
import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Badge: {
      props: z.object({
        label: z.string(),
        color: z.string().nullable(),
      }),
      slots: [],
      description: "A colored badge label",
    },
  },
});

Standard Components

Root

Component	Description
Frame	Root image container. Defines width, height, and background. Must be the root element.

Layout

Component	Description
Box	Generic container with padding, margin, background, border, and flex alignment.
Row	Horizontal flex layout with gap, align, justify.
Column	Vertical flex layout with gap, align, justify.

Content

Component	Description
Heading	h1-h4 heading text with color and alignment.
Text	Body text with fontSize, color, weight, style, and alignment.
Image	Image from a URL with width, height, and borderRadius.

Decorative

Component	Description
Divider	Horizontal line separator.
Spacer	Empty vertical space.

Server-Side APIs

import { renderToSvg, renderToPng } from "@json-render/image/render";

// Render to an SVG string
const svg = await renderToSvg(spec, { fonts });

// Render to a PNG buffer (requires @resvg/resvg-js)
const png = await renderToPng(spec, { fonts });

Options

Option	Type	Default	Description
fonts	SatoriOptions['fonts']	[]	Font data for text rendering
width	number	Frame prop	Override image width
height	number	Frame prop	Override image height
registry	Record<string, Component>	{}	Custom component overrides
includeStandard	boolean	true	Include standard components
state	Record<string, unknown>	{}	Initial state values

Server-Safe Import

Import schema and catalog definitions without pulling in React or Satori:

import { schema, standardComponentDefinitions } from "@json-render/image/server";

License

Apache-2.0