@nuxt/fonts

Nuxt OG Image uses @nuxt/fonts for font management. This is required for custom fonts.

Setup

1. Install @nuxt/fonts:

npx nuxi module add @nuxt/fonts

2. Configure your fonts in nuxt.config.ts with global: true:

export default defineNuxtConfig({
  modules: ['@nuxt/fonts', 'nuxt-og-image'],

  fonts: {
    families: [
      { name: 'Inter', weights: [400, 700], global: true },
    ],
  },
})

3. Use the font in your OG Image template:

<template>
  <div style="font-family: 'Inter'">
    <h1>{{ title }}</h1>
  </div>
</template>

How It Works

1. Build time: Nuxt OG Image resolves your configured font families using the same providers as @nuxt/fonts
2. Runtime: Fonts are fetched from provider URLs (e.g., Google Fonts) and cached
3. No @nuxt/fonts: If not installed, no fonts are available for rendering

Provider Configuration

Use any provider supported by @nuxt/fonts:

export default defineNuxtConfig({
  fonts: {
    families: [
      // Google Fonts (default provider)
      { name: 'Roboto', weights: [400, 700], global: true },

      // Explicit provider
      { name: 'Inter', provider: 'bunny', weights: [400, 700], global: true },

      // Local fonts (must be woff2 format)
      {
        name: 'MyFont',
        src: '/fonts/MyFont.woff2',
        weight: 400,
        global: true,
      },
    ],
  },
})

Font Format

Different renderers support different font formats:

Troubleshooting

Font not rendering

1. Ensure the font has global: true set
2. Ensure the font is listed in fonts.families
3. For local fonts, ensure format matches your renderer (see table above)

China/Blocked regions

For regions where Google Fonts is blocked, use local fonts or an alternative provider:

export default defineNuxtConfig({
  fonts: {
    providers: {
      google: false,
    },
    families: [
      {
        name: 'Inter',
        src: '/fonts/Inter-Regular.woff2',
        weight: 400,
        global: true,
      },
    ],
  }
})