API Reference

Core (@better-og/core)

Presets

const STANDARD: AspectRatioPreset; // 1200x630,  1.91:1
const SQUARE: AspectRatioPreset; // 1200x1200, 1:1
const PORTRAIT: AspectRatioPreset; // 630x1200,  1:1.91
const INSTAGRAM: AspectRatioPreset; // 1200x1500, 4:5

Functions

detectPlatform(request: Request, options?): Promise<DetectedPlatform>

Detects the requesting platform using query overrides plus request signals such as User-Agent and Referer.

resolveOgRequest(request: Request, options?): Promise<ResolvedOgRequest>

Returns the normalized render plan, including platform, aspect ratio, dimensions, safe area, layout strategy, layout boxes, capabilities, and matched detection signals.

resolveFontSetup(options: ResolveFontSetupOptions): Promise<ResolvedFontSetup>

Resolves base fonts and script-aware fallback fonts, returning both the font data and family name mappings.

loadGoogleFonts(options: LoadGoogleFontsOptions): Promise<Font[]>

Loads font data from Google Fonts. Works in any runtime.

clearFontCache(): void

Clears the in-memory Google Fonts cache.

resolveLocaleFromParams(params): string | undefined

Extracts locale from route params, checking params.lang, params.locale, then first truthy value.

getSafeArea(options): OgSafeArea

Returns computed platform-specific safe area insets for the resolved canvas size.

createLayout(options): OgLayout

Builds reusable layout boxes (canvas, safe, content, center, bleed) for an OG canvas.

Types

interface AspectRatioPreset {
  label: string;
  width: number;
  height: number;
}

interface Font {
  name?: string;
  data: ArrayBuffer | Uint8Array;
  weight?: number;
  style?: string;
}

interface ResolvedOgRequest {
  aspectRatio: string;
  width: number;
  height: number;
  platform: string;
  safeArea: OgSafeArea;
  layoutStrategy: "wide" | "square" | "portrait";
  layout: OgLayout;
  capabilities: PlatformCapabilities;
}

interface OgSafeArea {
  top: number;
  right: number;
  bottom: number;
  left: number;
}

interface ResolveFontSetupOptions {
  baseFonts?: Font[];
  fallbackLocales?: string[];
  locale?: string;
  request?: Request;
  sources?: FontSource[];
  text?: string;
}

interface ResolvedFontSetup {
  families: {
    base?: string;
    locales: Record<string, string>;
  };
  fonts: Font[];
}

Next.js (@better-og/next)

createOgRouteHandler(options)

Creates a Next.js route handler for OG image generation.

loadGoogleFontForImageResponse(options)

Loads Google Fonts in a format compatible with next/og ImageResponse.

withOgRewrite(request, options?)

Middleware helper that resolves the request plan and rewrites the URL with normalized platform, layout, and aspect_ratio query parameters.

Next.js Edge (@better-og/next/edge)

createOgRouteHandler(options)

Same interface as @better-og/next but for the Edge runtime. Only supports the next renderer.