TemplateRenderer - OGify | Generate beautiful Open Graph images in minutes

The main class for managing templates and rendering images. Typically created via createRenderer(), but can be instantiated directly if needed.

For complete type definitions and interfaces, see the Type Definitions page.

Methods

getTemplate

Retrieves a template by its unique ID.

getTemplate(id: string): OgTemplate | undefined

Parameters

string

required

The template ID to look up

Returns

template

OgTemplate | undefined

The template definition, or undefined if not found

renderToImage

Renders a template to a PNG image buffer. This is the main method for generating OG images.

renderToImage<K extends keyof TMap>(
  templateId: K,
  params: TMap[K] | (() => Promise<TMap[K]>),
  options?: OgTemplateOptions
): Promise<Buffer>

Parameters

templateId

string

required

The ID of the template to render

params

object | function

required

Parameters specific to the chosen template, or a function returning a Promise of parameters. User-provided parameters override shared parameters.

options

OgTemplateOptions

Rendering options

Show properties

width

number

default:1200

Width of the image in pixels. Templates always receive the original width/height — scale is applied during rasterisation.

height

number

default:630

Height of the image in pixels

isRTL

boolean

default:false

Whether to enable Right-to-Left support

fonts

OgFontConfig[]

Custom fonts override

scale

number

default:1

Supersampling scale factor for higher-quality PNG output. Satori renders the SVG at the original width × height; Resvg rasterises it at width × scale pixels wide. Clamped to [1, 4]. Float values are supported (1.5, 2, etc.). Do not use for layout — see Scale & Supersampling.

Returns

buffer

Promise<Buffer>

A promise that resolves to the PNG image buffer

Rendering process

Template Lookup

Looks up the template by ID in the internal registry

Parameter Merging

Merges shared params with user paramsPriority: Parameters are merged with the following precedence (highest to lowest):

params passed to renderToImage()
sharedParams from renderer configuration
Template default parameters

Cache Checking

Generates a cache key and checks for a cached PNG buffer

Inflight Deduplication

If an identical render is already in progress, returns the shared in-flight promise instead of starting a duplicate render

Before Render Hook

Calls beforeRender hook if configured

Core Rendering

Delegates to the core rendering engine

Cache Storage

Caches the generated image

After Render Hook

Calls afterRender hook if configured

Return Buffer

Returns the PNG buffer

Examples

const buffer = await renderer.renderToImage("basic", {
  title: "Hello World",
  layout: "centered",
});

const buffer = await renderer.renderToImage("basic", async () => {
  const data = await fetchBlogPost();
  return {
    title: data.title,
    subtitle: data.excerpt,
  };
});

const buffer = await renderer.renderToImage(
  "basic",
  {
    title: "مرحبا بالعالم",
  },
  {
    isRTL: true,
  }
);

const buffer = await renderer.renderToImage(
  "basic",
  {
    title: "Custom Size",
  },
  {
    width: 1600,
    height: 900,
  }
);

// Renders at 1200×630 layout, rasterised at 2400×1260 PNG
const buffer = await renderer.renderToImage(
  "basic",
  {
    title: "Sharp Retina Image",
  },
  {
    scale: 2, // @2x — recommended for retina displays
  }
);

// Fine-grained float values also work
const buffer2 = await renderer.renderToImage(
  "basic",
  { title: "Quality Boost" },
  { scale: 1.5 }
);

Usage Example

import { createRenderer } from "@ogify/core";
import basicTemplate from "@ogify/templates/basic";
import type { TemplateParams } from "@ogify/templates/basic";

const renderer = createRenderer<{ basic: TemplateParams }>({
  templates: { basic: basicTemplate },
});

// Get template info
const template = renderer.getTemplate("basic");
console.log(template?.fonts);

// Render image
const buffer = await renderer.renderToImage("basic", {
  title: "My Page",
  subtitle: "A great description",
  layout: "centered",
});

// Save or return the buffer
await writeFile("og-image.png", buffer);

​Methods

​getTemplate

​Parameters

​Returns

​renderToImage

​Parameters

​Returns

​Rendering process

​Examples

​Usage Example

Methods

getTemplate

Parameters

Returns

renderToImage

Parameters

Returns

Rendering process

Examples

Usage Example