Skip to main content
Complete TypeScript type definitions for the @ogify/core library. These types provide full type safety when creating templates and configuring renderers.

​
Core Types

​
OgTemplateParams

Base type for template parameters. All template parameter types should extend this. 
type OgTemplateParams = Record<string, string | string[] | number | boolean>;
Parameters are the data that gets injected into templates to create personalized OG images. Values can be:
  • Strings: Text content (titles, descriptions, names)
  • String Arrays: Lists of tags, categories
  • Numbers: Counts, dates, metrics
  • Booleans: Flags, toggles, states
const params: OgTemplateParams = {
  title: "My Blog Post",
  author: "John Doe",
  views: 1234,
  published: true,
  tags: ["typescript", "web development"],
};

​
OgTemplate

Complete definition of an Open Graph image template. A template is a reusable blueprint for generating OG images. 
type OgTemplate<TParams = OgTemplateParams> = {
  renderer: (props: OgTemplateOptions & { params: TParams }) => string;
  fonts: OgFontConfig[];
  emojiProvider?: OgEmojiProvider;
};
​
renderer
function
required
Function that generates HTML markup from template parameters. The HTML should use inline styles (Tailwind-like utilities are supported). Flexbox and basic CSS properties are supported by Satori.
​
fonts
OgFontConfig[]
required
Custom fonts to use in this template. Fonts are loaded in the order specified and should cover all characters used in the template.
​
emojiProvider
OgEmojiProvider
Optional emoji provider to use in this template. If not specified, defaults to 'noto'.

​
OgTemplateRenderer

Configuration for the TemplateRenderer class. Defines available templates, global defaults, and lifecycle hooks. 
type OgTemplateRenderer<
  TMap extends Record<string, OgTemplateParams> = Record<
    string,
    OgTemplateParams
  >
> = {
  templates: { [K in keyof TMap]: OgTemplate<TMap[K]> };
  sharedParams?:
    | Partial<TMap[keyof TMap]>
    | (() => Promise<Partial<TMap[keyof TMap]>>);
  cache?: OgCacheConfig;
  beforeRender?: (
    templateId: keyof TMap,
    params: TMap[keyof TMap]
  ) => void | Promise<void>;
  afterRender?: (
    templateId: keyof TMap,
    params: TMap[keyof TMap],
    imageBuffer: Buffer
  ) => void | Promise<void>;
};
​
templates
object
required
Map of template definitions to register, keyed by template ID
​
sharedParams
object | function
Shared parameter values applied to all templates. These values are merged with user-provided parameters, with user values taking precedence.
​
cache
OgCacheConfig
Cache configuration for fonts and icons. When provided, enables LRU caching to improve performance by reducing redundant network requests.
​
beforeRender
function
Hook called before rendering. Useful for logging, analytics, parameter validation, authentication checks, and rate limiting.
​
afterRender
function
Hook called after rendering. Useful for caching generated images, cleanup operations, sending notifications, and updating metrics.

​
Font Configuration

​
OgFontConfig

Configuration for a font used in OG image templates. Fonts can be loaded from three sources (in priority order):
  1. Pre-loaded binary data (via data property)
  2. Remote URL (via url property)
  3. Google Fonts API (automatic detection based on name)
type OgFontConfig = {
  name: string;
  weight?: FontWeight;
  style?: FontStyle;
  url?: string;
  data?: Buffer | ArrayBuffer;
  format?: OgFontFormat;
};
​
name
string
required
The font family name (e.g., ‘Inter’, ‘Roboto’, ‘Merriweather’)
​
weight
number
default:400
Font weight (100-900)
​
style
'normal' | 'italic'
default:"normal"
Font style
​
url
string
URL to the font file (for custom/self-hosted fonts)
​
data
Buffer | ArrayBuffer
Pre-loaded font binary data
​
format
'woff' | 'ttf'
default:"woff"
Font file format
const font1: OgFontConfig = {
  name: "Inter",
  weight: 400,
  style: "normal",
};

​
OgFontFormat

Supported font file formats. 
type OgFontFormat = "woff" | "ttf";
  • woff: Web Open Font Format (modern, compressed)
  • ttf: TrueType Font (legacy, larger file size)

​
Template Options

​
OgTemplateOptions

Props passed to template HTML rendering functions. Contains user-provided parameters and optional dimension overrides. 
type OgTemplateOptions = {
  fonts?: OgFontConfig[];
  emojiProvider?: OgEmojiProvider;
  width?: number;
  height?: number;
  isRTL?: boolean;
};
​
fonts
OgFontConfig[]
Custom fonts to use in this template
​
emojiProvider
OgEmojiProvider
Optional emoji provider to use in this template
​
width
number
default:1200
Optional custom width in pixels
​
height
number
default:630
Optional custom height in pixels
​
isRTL
boolean
default:false
Enable Right-to-Left text direction
const html = (props: OgTemplateOptions) => `
  <div style="width: ${props.width}px; height: ${props.height}px">
    <h1>${props.params.title}</h1>
    <p>${props.params.description}</p>
  </div>
`;

​
Emoji Providers

​
OgEmojiProvider

Supported emoji providers for rendering emoji characters in OG images. Each provider offers a different visual style. 
type OgEmojiProvider =
  | "twemoji"
  | "fluent"
  | "fluentFlat"
  | "noto"
  | "blobmoji"
  | "openmoji";
Twitter’s emoji set - colorful, rounded style
Microsoft’s Fluent emoji - 3D style with color
Microsoft’s Fluent emoji - flat 2D style
Google’s Noto Color Emoji - current standard (default)
Google’s blob-style emoji - deprecated but still available
Open-source emoji with outlined style

​
Caching

​
OgCacheConfig

Cache configuration for fonts and icons. Supports two caching strategies: memory and filesystem. 
type OgCacheConfig =
  | {
      type: "memory";
      ttl?: number;
      max?: number;
    }
  | {
      type: "filesystem";
      dir?: string;
      ttl?: number;
      max?: number;
    };
Fast in-memory cache with LRU eviction
​
type
'memory'
required
Memory-based caching strategy
​
ttl
number
default:3600000
Time-to-live in milliseconds (default: 1 hour)
​
max
number
default:100
Maximum number of items to cache
const cache: OgCacheConfig = {
  type: 'memory',
  ttl: 3600000, // 1 hour
  max: 100
};