OGX v0.3.0 introduces Universal Font Loading - load any Google Font or custom local fonts without bundling. Fonts are loaded from CDN by default.

Quick Start

import { fontRegistry } from '@ogxjs/core';

// Load any Google Font by name
await fontRegistry.registerGoogleFont('Poppins', [400, 600, 700]);

// Or use Inter (default)
await fontRegistry.registerInterFromUrl([400, 700]);

Loading Strategies

1. Google Fonts (Recommended)

Load any Google Font by name using Bunny Fonts CDN (privacy-friendly):

import { loadGoogleFont, fontRegistry } from '@ogxjs/core';

// Direct loading
const fonts = await loadGoogleFont('Roboto', [400, 700]);

// Or register globally
await fontRegistry.registerGoogleFont('Playfair Display', [400, 700, 900]);
await fontRegistry.registerGoogleFont('Inter', [400, 600]);

Available fonts: Any font from Google Fonts works automatically.

Weights: Common weights are 100, 200, 300, 400, 500, 600, 700, 800, 900.

2. Inter Font (Default Fallback)

If no fonts are registered, OGX loads Inter from CDN automatically:

import { fontRegistry } from '@ogxjs/core';

// Explicit registration (recommended for control)
await fontRegistry.registerInterFromUrl([400, 700]);

3. Custom Local Fonts

Load fonts from your project's file system:

import { loadFontFromFile, fontRegistry } from '@ogxjs/core';
import path from 'path';

// Direct loading
const brandFont = await loadFontFromFile(
  path.join(process.cwd(), 'public/fonts/BrandFont.woff2'),
  { name: 'BrandFont', weight: 700 }
);

// Or register globally
await fontRegistry.registerFontFromFile(
  './app/fonts/CustomFont.woff2',
  { name: 'CustomFont', weight: 400 }
);

[!NOTE] Local font loading only works in Node.js environments (Route Handlers, API routes). Use CDN loading for Edge runtimes.

Usage Patterns

Pattern 1: On-Demand Loading

Load fonts in each route handler:

// app/api/og/route.tsx
import { ogx, loadGoogleFont } from '@ogxjs/core';

export async function GET() {
  const fonts = await loadGoogleFont('Poppins', [400, 700]);
  
  const image = await ogx({
    preset: 'blog',
    slots: { title: 'My Post' },
    fonts,
  });
  
  return new Response(image, {
    headers: { 'Content-Type': 'image/png' }
  });
}

Pattern 2: Global Registry (Recommended)

// app/lib/fonts.ts
import { fontRegistry } from '@ogxjs/core';

export async function initializeFonts() {
  await fontRegistry.registerGoogleFont('Inter', [400, 600, 700]);
}

// app/layout.tsx
import { initializeFonts } from './lib/fonts';
initializeFonts();

// app/api/og/route.tsx
import { ogx } from '@ogxjs/core';

export async function GET() {
  // No fonts needed - uses registry automatically
  const image = await ogx({
    preset: 'blog',
    slots: { title: 'My Post' }
  });
  
  return new Response(image, {
    headers: { 'Content-Type': 'image/png' }
  });
}

API Reference

`loadGoogleFont(fontName, weights)`

Load any Google Font by name.

const fonts = await loadGoogleFont('Roboto', [400, 700]);
// Returns: FontConfig[]

`loadFontFromFile(path, options)`

Load a font from a local file.

const font = await loadFontFromFile('./fonts/Custom.woff2', {
  name: 'CustomFont',
  weight: 400,
  style: 'normal' // optional
});
// Returns: FontConfig

`fontRegistry.registerGoogleFont(fontName, weights)`

await fontRegistry.registerGoogleFont('Poppins', [400, 600, 700]);

`fontRegistry.registerFontFromFile(path, options)`

await fontRegistry.registerFontFromFile('./fonts/Brand.woff2', {
  name: 'Brand',
  weight: 700
});

`fontRegistry.registerInterFromUrl(weights)`

await fontRegistry.registerInterFromUrl([400, 700]);

`fontRegistry.getFonts()`

Get all registered fonts.

const fonts = fontRegistry.getFonts();
// Returns: FontConfig[]

Deprecated APIs

[!WARNING] The following APIs are deprecated and will be removed in v1.0.0:

Deprecated	Use Instead
`loadInterFont()`	`loadInterFromUrl()`
`fontRegistry.registerInterFromUrl()`	`fontRegistry.registerInterFromUrl()`

These APIs were used to load fonts from bundled files. Since v0.3.0, fonts are loaded from CDN by default, eliminating the need for bundled font files.

Technical Notes

CDN Provider

OGX uses Bunny Fonts - a privacy-friendly Google Fonts mirror. No user tracking.

Caching

Fonts are cached in memory after the first load. Subsequent renders reuse cached fonts.

Edge Runtime Compatibility

CDN-based loading works everywhere:

✅ Vercel Edge Functions
✅ Cloudflare Workers
✅ Node.js
✅ Bun
✅ Deno

Local file loading (loadFontFromFile) requires Node.js filesystem access.

Fonts

On this page