Core Concepts

Platform Detection

When a social platform fetches your OG image, it sends a characteristic request signature. Better OG combines explicit query overrides with User-Agent, Referer, and other request hints to determine which platform is requesting the image and selects the optimal aspect ratio preset.

Aspect Ratio Presets

Four built-in presets cover the most common OG image dimensions:

import { INSTAGRAM, PORTRAIT, SQUARE, STANDARD } from "@better-og/core";

STANDARD; // { width: 1200, height: 630,  label: "1.91:1" }
SQUARE; // { width: 1200, height: 1200, label: "1:1"    }
PORTRAIT; // { width: 630,  height: 1200, label: "1:1.91" }
INSTAGRAM; // { width: 1200, height: 1500, label: "4:5"    }

You can also pass aspect ratio values via the ?aspect_ratio= query parameter. Supported aliases include standard, square, portrait, instagram, and explicit dimension strings like 1200x630.

OG Request

The resolved request object is passed to your component factory function and contains everything you need to render a platform-aware image:

interface ResolvedOgRequest {
  aspectRatio: string; // e.g. "1.91:1"
  width: number; // e.g. 1200
  height: number; // e.g. 630
  platform: string; // e.g. "twitter"
  safeArea: OgSafeArea; // platform-specific insets
  layoutStrategy: "wide" | "square" | "portrait";
  layout: OgLayout;
}

Safe Areas

Some platforms crop OG images. Twitter, for example, crops the bottom 44px of a standard OG image to overlay engagement buttons. Better OG exposes this as safeArea.bottom:

const handler = createOgRouteHandler({
  component: (ogContext) => (
    <div
      style={{
        paddingBottom: 32 + ogContext.safeArea.bottom,
      }}
    >
      {/* Content stays above the crop zone */}
    </div>
  ),
});

Middleware Rewrite Flow

The withOgRewrite middleware works as follows:

1. Intercepts requests matching the OG pathname prefix (default /og).
2. Skips if aspect_ratio is already in the query string.
3. Calls resolveOgRequest(request) to detect the platform and normalize the render plan.
4. Rewrites the URL with the resolved platform, layout, and aspect_ratio query parameters.

This ensures OG route handlers always receive a normalized aspect ratio without exposing it in the public URL.