Nuxt OG Image

nuxt-og-image provides several ways to generate Open Graph (OG) images to improve social media click-through rates:

• Vue Component Templates: Create custom og:image designs using Vue components.
• Rendering Engines:
  • Satori: High-performance rendering using Tailwind / UnoCSS, Google fonts, and emoji support.
  • Takumi: An alternative rendering engine.
  • Browser Prerendering: Supports complex templates by using a browser-based approach.
• Page Screenshots: Automatically generate screenshots for every page with options to hide specific elements or wait for animations.
• DevTools Integration: Use the Nuxt DevTools OG Image Playground to design and test images with full Hot Module Replacement (HMR).
• Edge Compatibility: Works on Vercel Edge, Netlify Edge, and Cloudflare Workers.

Nuxt OG Image is a module for Nuxt that generates social media preview images (og:image) using Vue templates. It automates the creation of Open Graph meta tags, ensuring that when your site links are shared on social media or chat platforms, they are accompanied by a visually appealing preview image.

Images can be rendered at build time or on-demand using one of three available renderers:

• Takumi (Recommended): Offers 2-10x faster rendering with complete CSS support.
• Satori: The original renderer with good CSS support.
• Browser: Uses a browser to prerender, providing full CSS support for highly complex templates.

This module helps improve click-through rates by making shared links more engaging through consistent and dynamic social previews.

Nuxt OG Image provides several capabilities for managing social previews:

• Template Flexibility: Create images using built-in templates or design your own using standard Vue components.
• DevTools Integration: Design and test images in real-time using the Nuxt DevTools OG Image Playground with full Hot Module Replacement (HMR).
• Renderer Options: Choose between Takumi (fastest/recommended), Satori, or Browser (fullest CSS support) depending on your needs.
• Styling & Assets: Supports Tailwind CSS, custom fonts, and emoji across all renderers.
• Screenshot Mode: Automatically generate screenshots for every page by hiding specific elements or waiting for animations.
• Edge Compatibility: Works seamlessly on edge runtimes including Vercel Edge, Netlify Edge, and Cloudflare Workers.

Choosing the right format depends on the content of your image and how social platforms process it:

• Use PNG (Default): For images containing text, logos, or flat colors. This maintains sharp edges and readability.
• Use JPEG: For images that are primarily photographs or contain complex gradients where file size reduction is the priority.

Important Quality Tip: Most social platforms (Twitter, Facebook, etc.) compress images into JPEG format upon upload. To avoid "double compression" artifacts, it is often better to upload a high-quality, crisp PNG rather than an already-compressed JPEG.

The build cache is managed automatically. It invalidates and regenerates images when:

• Options change: Any change to the title, description, or other props used to generate the image.
• Template changes: The component file used for rendering is modified.
• Module version changes: You upgrade the nuxt-og-image package.

Automatic Cleanup: To prevent unbounded storage growth, orphaned cache files (images no longer being generated) are automatically deleted if they are older than 7 days. This ensures social platforms can still reference existing images for a short period after they are removed from your site.

The level of CSS layout support depends on the renderer you have selected.

• Takumi and Browser renderers offer broad support, including Flexbox, CSS Grid, Block/Inline layouts, and Position Absolute.
• Satori is more constrained: it treats everything as a flexbox with flex-direction: column by default. It does not support display: grid, display: block, or display: inline.

| Feature | Takumi | Satori | Browser |
|---------|--------|--------|----------|
| **Flexbox** | ✅ | ✅ | ✅ |
| **CSS Grid** | ✅ | ❌ | ✅ |
| **Block/Inline** | ✅ | ❌ | ✅ |
| **Position Absolute** | ✅ | ✅ | ✅ |

The cacheVersion option allows you to control how the module namespaces its cache keys.

• Default: Uses the module's version number. This ensures that when you upgrade the module, the cache is automatically invalidated.
• Static Value: Setting a value like 'v1' will persist the cache across module updates.
• Disable: Setting it to false disables versioning entirely.

The key option in a variant configuration controls which meta tags are generated for that specific image variant:

Because WhatsApp uses og:image tags, providing multiple variants with unique keys (other than 'og' or 'twitter') allows WhatsApp to choose from multiple og:image options. WhatsApp typically selects the first image that meets its size requirements.

OG Image components must now include a renderer suffix in their filename to enable automatic detection, multiple variants, and tree-shaking. The CLI migration command handles this automatically.

Supported Suffixes:

• .satori.vue (for Satori renderer)
• .takumi.vue (for Takumi renderer)
• .browser.vue (for Browser renderer)

Example Structure:

components/OgImage/
  MyTemplate.satori.vue
  MyTemplate.takumi.vue

Nuxt OG Image v6 provides first-class CSS support via build-time processing. This replaces the UnoCSS runtime transformer.

Supported Features:

• Tailwind v4: Native support with build-time class extraction. Works with @nuxtjs/tailwindcss or the Vite plugin.
• UnoCSS: Full support.
• CSS Variables: Use your app's CSS custom properties directly in templates.
• Nuxt UI v3: Automatically resolves semantic colors (e.g., primary, secondary) from your app.config.ts.
• Theme Customization: Automatically resolves values defined in Tailwind @theme blocks.

/* assets/css/main.css */
@import "tailwindcss";

@theme {
  --color-brand: #ff6600;
  --font-heading: "Inter", sans-serif;
}

<!-- components/OgImage/MyTemplate.satori.vue -->
<template>
  <div class="bg-brand font-heading">
    Works!
  </div>
</template>

The Browser renderer uses a real browser to take screenshots, providing full CSS support for any design you can build. It also allows rendering JPEGs without requiring sharp and makes page screenshots simple.

When to use: It is highly recommended only when you are prerendering all of your images. It is much slower than Satori or Takumi and is not recommended for runtime use due to performance constraints.

<!-- Use the .browser.vue suffix to trigger the renderer -->
<!-- components/OgImage/MyTemplate.browser.vue -->