v6 Release

[harlan-zw]

Nuxt OG Image v6 is the next major release.

Nuxt OG Image v6 brings a complete overhaul focused on performance, modern tooling, and developer experience — with smaller bundles, native Tailwind v4 support, and powerful new features like multiple images per page.

📣 Highlights

Smaller, Faster Bundles

v6 takes an "opt-in" approach to renderer dependencies. Instead of bundling satori, resvg, and other heavy packages, you install only what you need. This means:

• Smaller node_modules — no unused renderer code
• Faster installs — especially in CI
• Better compatibility — choose the right binding for your runtime (Node.js vs Edge)

Running nuxi dev will prompt you to install the right packages automatically.

Smarter Caching

OG images are now cached more intelligently at every layer:

• Build cache (#413) — prerendered images are cached between builds, so unchanged pages don't regenerate
• CDN-friendly URLs (#305) — new Cloudinary-style URL encoding puts all options in the path (/_og/s/w_1200,title_Hello.png), making identical requests produce identical URLs for automatic CDN caching
• Cleaner cache keys (#427) — query params excluded by default, preventing cache fragmentation from tracking params like ?utm_source

Native Tailwind v4 Support

The legacy UnoCSS runtime transformer is gone. In its place: native Tailwind v4 integration that extracts classes at build time and compiles them with Tailwind's CSS engine. Your @theme customizations and Nuxt UI v3 semantic colors just work.

Multiple OG Images Per Page

Platforms like WhatsApp require square images while Twitter expects landscape. Now you can define multiple images per page with different dimensions:

defineOgImage([
  { title: 'My Page' }, // Default 1200x630
  { title: 'My Page', key: 'whatsapp', width: 800, height: 800 }, // Square for WhatsApp
])

⚡ Install Renderer Dependencies

Renderer dependencies are no longer bundled. Install what you need based on your renderer and runtime.

See PR #415.

Satori (default):

npm i satori @resvg/resvg-js        # Node.js
npm i satori @resvg/resvg-wasm      # Edge runtimes

Takumi (2-10x faster for simple templates):

npm i @takumi-rs/core               # Node.js
npm i @takumi-rs/wasm               # Edge runtimes

Chromium:

npm i playwright-core

🎨 Native Tailwind v4 Support

The UnoCSS runtime has been replaced with native Tailwind v4 support. Classes are extracted at build time and compiled with Tailwind's CSS engine.

See PR #430.

If using @nuxtjs/tailwindcss: No configuration needed.

If using Tailwind v4 with the Vite plugin:

export default defineNuxtConfig({
  ogImage: {
    tailwindCss: '~/assets/css/main.css'
  }
})

Custom @theme values and Nuxt UI v3 semantic colors (primary, secondary, etc.) are automatically resolved.

🖼️ Multiple OG Images Per Page

Define multiple images with different dimensions for different platforms.

See PR #305.

defineOgImage([
  { title: 'My Page' }, // Default for Twitter/Facebook
  { title: 'My Page', key: 'whatsapp', width: 800, height: 800 }, // Square for WhatsApp
])

The key option controls which meta tags are generated:

• 'og' (default) — generates both og:image and twitter:image
• 'twitter' — generates only twitter:image
• Any other string — generates only og:image

🔤 @nuxt/fonts Integration

Custom fonts now use @nuxt/fonts instead of the legacy ogImage.fonts config.

See PR #432.

export default defineNuxtConfig({
  modules: ['@nuxt/fonts', 'nuxt-og-image'],
  fonts: {
    families: [
      { name: 'Inter', weights: [400, 700], global: true }
    ]
  }
})

The global: true option is required for fonts to be available in OG Image rendering.

📦 Component Renderer Suffix

OG Image components now require a renderer suffix in their filename. This enables automatic renderer detection, multiple renderer variants, and tree-shaking.

See PR #433.

# Before
components/OgImage/MyTemplate.vue

# After
components/OgImage/MyTemplate.satori.vue
components/OgImage/MyTemplate.takumi.vue    # Optional: faster variant

Run the migration CLI to rename automatically:

npx nuxt-og-image migrate v6

🚀 Takumi Renderer

Takumi is a new Rust-based renderer offering 2-10x faster image generation for simple templates.

See PR #414.

export default defineNuxtConfig({
  ogImage: {
    defaults: { renderer: 'takumi' }
  }
})

Best for solid-color templates without gradients or opacity. See the Takumi docs for supported features.

🏷️ Community Templates Must Be Ejected

Community templates (NuxtSeo, SimpleBlog, etc.) are no longer bundled in production. Eject them to your project before building.

See PR #426.

npx nuxt-og-image eject NuxtSeo

Templates continue to work in development without ejecting.

🔗 New URL Structure

OG Image URLs now use a Cloudinary-style format with options encoded in the path. This enables better CDN caching since identical options produce identical URLs.

See PR #305.

v5	v6
/__og-image__/image/	/_og/d/
/__og-image__/static/	/_og/s/

🐛 Bug Fixes

• ff3bbd06 fix: require nuxt/fonts v0.13
• 055eadf9 fix: improved HMR
• 265cad56 fix: auto-eject components in dev
• 09d24449 fix: exclude default options from URLs (#431)
• 4ccd29e4 fix: always fallback to emoji fetching in edge runtimes (#429)
• 7b5b1af8 fix: avoid crashing main thread with resvg errors
• 97fb4b25 fix: support local fonts with zeroRuntime mode (#428)
• d22ede31 fix: support error.vue navigation
• 10886c92 fix: dynamic runtime cache storage (#425)
• 16ed4bf4 fix: force social platform cache invalidation between builds (#423)
• 349bd59a fix(satori): encoding bug for array text children (#422)
• 05f43596 fix: flakey images (#421)
• bbeeea16 fix: light-weight emoji resolves

📖 Migration Guide

Full migration guide: https://nuxtseo.com/og-image/migration-guide/v6

Quick Migration

npx nuxt-og-image migrate v6

This will:

• Rename components to include renderer suffix
• Migrate defineOgImageComponent() → defineOgImage()

Breaking Changes by Impact

High Impact (most users):

• Install renderer dependencies (#415)
• Component renderer suffix required (#433)
• Community templates must be ejected (#426)

Medium Impact (specific configurations):

• @nuxt/fonts required for custom fonts (#432)
• defineOgImageComponent deprecated (#433)
• UnoCSS runtime removed (#430)

Low Impact (edge cases):

• Cache key changes (#427)
• URL path changes (#305)
• Nuxt Content v2 support removed (#410)
• Config options removed (#410)

[dargmuesli]

It says

@nuxt/fonts is now required for custom fonts

which I read as "if you want to use any other font than the default, install @nuxt/fonts" (I understand custom as != default). But I guess @nuxt/fonts is now required for any font, including one that is not configured to be not-Inter, right?