v3.0.0 · Nuxt OG Image · Nuxt SEO

[NuxtSEO](https://nuxtseo.com/ "Home")

- [Modules](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [Tools](https://nuxtseo.com/tools)
- [Pro](https://nuxtseo.com/pro)
- [Learn SEO](https://nuxtseo.com/learn-seo/nuxt) [Releases](https://nuxtseo.com/releases)

[1.4K](https://github.com/harlan-zw/nuxt-seo)

[Nuxt SEO on GitHub](https://github.com/harlan-zw/nuxt-seo)

**OG Image v6** is here! Looking for an older version? [View v5 docs](https://nuxtseo.com/docs/og-image/v5/getting-started/introduction).

[User Guides](https://nuxtseo.com/docs/og-image/getting-started/introduction)

[API](https://nuxtseo.com/docs/og-image/api/define-og-image)

[Releases](https://nuxtseo.com/docs/og-image/releases/v6)

OG Image

- [Switch to OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction)
- [Switch to Nuxt SEO](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [Switch to Robots](https://nuxtseo.com/docs/robots/getting-started/introduction)
- [Switch to Sitemap](https://nuxtseo.com/docs/sitemap/getting-started/introduction)
- [Switch to Schema.org](https://nuxtseo.com/docs/schema-org/getting-started/introduction)
- [Switch to Link Checker](https://nuxtseo.com/docs/link-checker/getting-started/introduction)
- [Switch to SEO Utils](https://nuxtseo.com/docs/seo-utils/getting-started/introduction)
- [Switch to Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction)
- [Switch to Skew Protection](https://nuxtseo.com/docs/skew-protection/getting-started/introduction)
- [Switch to AI Ready](https://nuxtseo.com/docs/ai-ready/getting-started/introduction)

Search…```k`` /`

v6 (latest)

- Playgrounds
- [Discord Support](https://discord.com/invite/275MBUBvgP)

### Changelog

### Migration Guides

- [v2 to v3](https://nuxtseo.com/docs/og-image/migration-guide/v3)
- [v5 to v6](https://nuxtseo.com/docs/og-image/migration-guide/v6)

### Releases

- [v6.0.0](https://nuxtseo.com/docs/og-image/releases/v6)
- [v5.0.0](https://nuxtseo.com/docs/og-image/releases/v5)
- [v4.0.0](https://nuxtseo.com/docs/og-image/releases/v4)
- [v3.0.0](https://nuxtseo.com/docs/og-image/releases/v3)
- [v2.0.0](https://nuxtseo.com/docs/og-image/releases/v2)

Releases

# v3.0.0

[Copy for LLMs](https://nuxtseo.com/docs/og-image/releases/v3.md)

## [Background](#background)

I'm excited to share the v3 of Nuxt OG Image is here.

This releases features:

- A complete rewrite of the module to improve stability and developer experience.
- Many new performance improvements, including a Zero Runtime mode.
- A new Playground with more features and community templates.

## [🚀 Features](#features)

### [✨ Zero Runtime Mode](#zero-runtime-mode)

Previously when using Nuxt as a server-side app with prerendered OG Images, you were forced to have runtime OG images as well which added significant overhead to the server build.

In v3 there's a Zero Runtime Mode which will strip all tree-shakable OG image generation code from the final build, reducing the size of the server bundle by 1.2mb and node_modules by 23mb.

See the [Zero Runtime Mode](https://nuxtseo.com/docs/og-image/guides/zero-runtime) guide for more information.

### [⛹️ Play Time: New Playground](#️-play-time-new-playground)

The playground has been redesigned with a focus on giving you more ways to preview and debug your templates. It introduces a number of tabs:

- **Design**

The default design view, this is the similar to v2 playground. It gives you HMR of the template, the ability to change the options used to render the template.

New features include a social media previews (Twitter, Slack), changing the rendering (Browser, Satori) and more.

v3

v2

![v3 preview of OG Image](https://github.com/harlan-zw/nuxt-og-image/assets/5326365/e337b490-dccb-4e58-972a-5e6e63f30986)

- **Templates**

See and preview all the OG templates available to you. You can select a template to switch to it.

This also introduces "Community Templates", which are templates designed by the community, accessible to you. There are 7 community templates so far and more to come. Feel free to submit your own.

![v3 gallery tab](https://github.com/harlan-zw/nuxt-og-image/assets/5326365/ab0f8d86-3167-4369-af2b-dfa4153a08ea)

- **Debug**

See the raw input and output of the template. This is useful for debugging your templates. Will be expanded in the future.

- **Docs**

An iframe of the module documentation.

### [🇹 Type Safety with `defineOgImageComponent`](#type-safety-with-defineogimagecomponent)

In v2, you had to define your config using `defineOgImage`. This was okay but the API provided minimal type safety.

In v3, you can now define your config using `defineOgImageComponent` which provides type safety by reading the type definitions from the component you're using.

```
defineOgImageComponent(
  // component name
  'NuxtSeo',
  // component props
  { title: 'Hello!' },
  // image options
  { alt: 'A welcome message' }
)
```

### [🍃 UnoCSS and Theming Support](#unocss-and-theming-support)

Satori itself provides a subset of [Tailwind CSS](https://tailwindcss.com) classes that you can use to style your templates. This is great but also limited.

With v3, the module now runs UnoCSS's [preset-wind](https://unocss.dev/presets/wind), loaded with your Tailwind / [UnoCSS](https://unocss.dev) theme config, before Satori.

```
export default defineConfig({
  theme: {
    fontSize: {
      'mega-big': '100px',
    },
    colors: {
      base: colors.white,
      primary: colors.green,
    },
  },
})
```

UnoCSS will convert any classes you use into inlined CSS for the `style` attribute. While this won't provide complete compatibility with Tailwind, it gives you access to a lot more classes than Satori alone.

```
<template>
  <div class="w-full h-full flex items-center justify-center bg-primary-500/50 text-base">
    <h1 class="text-mega-big">
      Custom Theme Classes!
    </h1>
  </div>
</template>
```

### [😁 More Emojis](#more-emojis)

In v2 we were limited to only `twemoji` emojis (Twitter Emojis).

In v3 we switch to using the [Iconify API](https://iconify.design/docs/api/) which gives us access to the following emoji families: `twemoji`, `noto`, `fluent-emoji`, `fluent-emoji-flat`, `fluent-emoji-high-contrast`, `noto-v1`, `emojione`, `emojione-monotone`, `emojione-v1`, `streamline-emojis`, `openmoji`

The default emoji family has been switched to `noto`, providing a more complete set of emojis and looks better generally.

### [🖼️ JPEG OG Images](#️-jpeg-og-images)

PNGs are great for most use cases, but they come at the cost of a larger file size.

For Browser based rendering, the module now renders `jpeg` images by default.

For Satori, you can now opt-in by adding a `sharp` dependency and switching the extension to `jpeg`.

See the [JPEGs](https://nuxtseo.com/docs/og-image/guides/jpegs) guide for more information.

### [📝 Nuxt Content integration](#nuxt-content-integration)

Using a component or composable with within your markdown content is awkward.

With v3, the module now supports the `ogImage` frontmatter key for configuring your OG Image. This will only work when you're using Document Driven mode, or you have set a `path`.

content/blog/3-months-of-europe.md

```
---
path: /blog/3-months-of-europe
ogImage:
  component: BlogOgImage
  props:
    image: /blog/3-months-of-europe.png
    readingMins: 5
---
```

### [🔄 OG Image Route Rule](#og-image-route-rule)

In some cases, you'll want to apply OG Image settings for a subset of pages. With the new route rule support, you can now handle this even easier.

This lets you provide a `ogImage` key that will be either used or merged into the existing OG Image options.

For example, this documentation website uses it to set the `icon` depending on your path.

```
export default defineNuxtConfig({
  routeRules: {
    '/og-image/**': {
      ogImage: {
        props: { icon: 'carbon:image-search' }
      }
    }
  }
})
```

### [Improved `css-inline` Compatibility](#improved-css-inline-compatibility)

Whenever you add a template has a `<style>` block, we need to use the [css-inline](https://github.com/Stranger6667/css-inline) dependency to make sure the styles get applied correctly.

This dependency previously only had compatibility for Node based environments. With work the library has done to add full Wasm support, we can now run this in all environments (Cloudflare support is still pending).

Note that the module won't enable this by default; you will need to install the dependency when prompted.

```
<template>
  <div>
    <h1 class="title" />
  </div>
</template>

<style scoped>
// just works in all environments now
.title {
  color: red;
}
</style>
```

## [✨ Improvements](#improvements)

### [New OG Image URL](#new-og-image-url)

The old pattern for OG images was `/<path>/__og_image__/og.png`, this has been changed to `/_og/d/<path>/og.<extension>`.

With this change, the route is no longer added as a middleware, meaning you can hook into the route yourself.

It also means it's easier to target using route rules if you want to make adjustments.

### [New OG Image Size](#new-og-image-size)

In v2 we render OG Images at 1200x630 (1:19), this was the recommended resolution from Facebook.

For better compatibility with other Social platforms, we now use 1200x600 (1:2). This particular will render OG Images better on WhatsApp.

### [Per-Template Custom Fonts](#per-template-custom-fonts)

Sometimes you'll be rendering a custom template that you want to use a custom font with, without having to load that font for all templates.

Now you can using `fonts` prop on the `defineOgImage` component.

```
defineOgImage({
  fonts: [
    'Noto+Sans:400'
  ]
})
```

See the [Custom Fonts](https://nuxtseo.com/docs/og-image/guides/custom-fonts) guide for more details.

### [Updated Default Template](#updated-default-template)

The default template is now called `NuxtSeo`. It now uses a more modern design, with a focus on readability.

It introduces a number of new props:

- `colorMode` - `light`, `dark`

Changes from a light or dark background / text color. Integrates with `@nuxtjs/color-mode`, selecting your default color mode.

- `theme` - `#${string}`

Change the hex color of the flare and the Nuxt SEO logo.

Theming

Light mode

Dark mode

![v3 dark mode](https://nuxtseo.com/_og/d/og-image/releases/v3/og.png?component=Release&theme=%23d946ef&siteName=Purple&icon=carbon%3Afire)

Learn more on the [NuxtSeo Template](https://nuxtseo.com/docs/og-image/guides/community-templates) docs.

### [Stale-While-Revalidate Caching](#stale-while-revalidate-caching)

When generating images at runtime, it's important that we cache them to reduce the load on your server.

While caching for v2 worked, it was of a mess with many configuration options.

In v3, the caching has been simplified to a single prop called `cacheMaxAgeSeconds` that by default, is set to `259200` (72 hours).

While not recommended, you can disable the caching by providing `cacheMaxAgeSeconds: 0`. You should instead opt for a lower cache time `cacheMaxAgeSeconds: 300` (5 minutes).

Stale-While-Revalidate is now enabled by default, it also will correctly respond with 304 Not Modified codes, avoiding extra bills for your hosting.

### [Prerendering Improvements](#prerendering-improvements)

With the introduction of the Nitro `prerender:config` hook ([#1519](https://github.com/unjs/nitro/pull/1519)), the module can now natively handle the prerendering of screenshots, allowing you to make use of concurrency.

This also means that if you're generating your app with `nuxi generate`, that the module will no longer bundle any Satori or [Playwright](https://playwright.dev) dependencies.

### [Pre-existing OG Images](#pre-existing-og-images)

In some cases, you'll have a page that you already have a designed OG Image for that you want to use instead of the dynamically generated one.

In those cases you can now provide a `url` to `defineOgImage` and all the tags will be set up properly for you.

```
defineOgImage({ url: 'https://example.com/og.png' })
```

### [Simple HTML OG Images](#simple-html-og-images)

If you want to simplify your integration, you can provide raw HTML to the `defineOgImage` composable instead of creating a new component.

```
defineOgImage({
  html: \`<div class="w-full h-full text-6xl flex justify-end items-end bg-blue-500 text-white">
    <div class="mb-10 underline mr-10">hello world</div>
</div>\`,
})
```

### [Opt-ing out of OG Images](#opt-ing-out-of-og-images)

On some pages, you may want to disable the OG Image generation, you can now do this with by providing a false value for the options.

```
// removes all of the og image tags
defineOgImage(false)
```

## [⚠️ Breaking Changes](#️-breaking-changes)

Trying to migrate? Check the [v2 to v3 migration guide](https://nuxtseo.com/docs/og-image/migration-guide/v3).

### [Nuxt Config](#nuxt-config)

- `playground` - the module removed this option; if you enable Nuxt DevTools, the module always enables the playground
- `runtimeBrowser` - the module removed this option
- `runtimeSatori` - the module removed this option

### [Nuxt Hooks](#nuxt-hooks)

- `og-image:prerenderScreenshots` is no longer supported
- `og-image:config` - the module removed this hook

### [OG Image Options](#og-image-options)

- `provider` renamed to `renderer`, the `browser` provider is now `browser`
- `cacheTtl` renamed to `cacheMaxAgeSeconds`; the module removed `cache`, `cacheKey`, and `static`
- You can no longer pass non-typed keys; you should provide props to the `props` key or use `defineOgImageComponent`.

The module now names the default template `NuxtSeo`, instead of `Fallback`.

### [Composables](#composables)

The module removed the following composables:

- `defineOgImageStatic`
- `defineOgImageDynamic`
- `defineOgImageCached`
- `defineOgImageWithoutCache`

### [Components](#components)

The module removed the following components:

- `OgImageStatic`
- `OgImageDynamic`
- `OgImageCached`
- `OgImageWithoutCache`

The remaining components `OgImage` and `OgImageScreenshot` are no longer global. If you need to use them with Nuxt Content, set `componentOptions`.

```
export default defineNuxtConfig({
  ogImage: {
    componentOptions: {
      global: true,
    },
  },
})
```

[Edit this page](https://github.com/nuxt-modules/og-image/edit/main/docs/content/7.releases/5.v3.md)

[Markdown For LLMs](https://nuxtseo.com/docs/og-image/releases/v3.md)

Did this page help you?

[v4.0.0 Release notes for Nuxt OG Image v4.](https://nuxtseo.com/docs/og-image/releases/v4) [v2.0.0 Stable release with runtime images, custom fonts, and improved caching.](https://nuxtseo.com/docs/og-image/releases/v2)

On this page

- [Background](#background)
- [🚀 Features](#features)
- [✨ Improvements](#improvements)
- [⚠️ Breaking Changes](#️-breaking-changes)

[GitHub](https://github.com/harlan-zw/nuxt-seo) [ Discord](https://discord.com/invite/275MBUBvgP)

### [NuxtSEO](https://nuxtseo.com/ "Home")

- [Getting Started](https://nuxtseo.com/docs/nuxt-seo/getting-started/introduction)
- [MCP](https://nuxtseo.com/docs/nuxt-seo/guides/mcp)

Modules

- [Robots](https://nuxtseo.com/docs/robots/getting-started/introduction)
- [Sitemap](https://nuxtseo.com/docs/sitemap/getting-started/introduction)
- [OG Image](https://nuxtseo.com/docs/og-image/getting-started/introduction)
- [Schema.org](https://nuxtseo.com/docs/schema-org/getting-started/introduction)
- [Link Checker](https://nuxtseo.com/docs/link-checker/getting-started/introduction)
- [SEO Utils](https://nuxtseo.com/docs/seo-utils/getting-started/introduction)
- [Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction)
- [Skew Protection](https://nuxtseo.com/docs/skew-protection/getting-started/introduction)
- [AI Ready](https://nuxtseo.com/docs/ai-ready/getting-started/introduction)

### [NuxtSEO Pro](https://nuxtseo.com/pro "Home")

- [Getting Started](https://nuxtseo.com/pro)
- [Dashboard](https://nuxtseo.com/pro/dashboard)
- [Pro MCP](https://nuxtseo.com/docs/nuxt-seo-pro/mcp/installation)

### [Learn SEO](https://nuxtseo.com/learn-seo "Learn SEO")

Nuxt

- [Mastering Meta](https://nuxtseo.com/learn-seo/nuxt/mastering-meta)
- [Controlling Crawlers](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers)
- [Launch & Listen](https://nuxtseo.com/learn-seo/nuxt/launch-and-listen)
- [Routes & Rendering](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering)
- [Staying Secure](https://nuxtseo.com/learn-seo/nuxt/routes-and-rendering/security)

Vue

- [Vue SEO Guide](https://nuxtseo.com/learn-seo/vue)
- [Mastering Meta](https://nuxtseo.com/learn-seo/vue/mastering-meta)
- [Controlling Crawlers](https://nuxtseo.com/learn-seo/vue/controlling-crawlers)
- [SPA SEO](https://nuxtseo.com/learn-seo/vue/spa)
- [SSR Frameworks](https://nuxtseo.com/learn-seo/vue/ssr-frameworks)
- [SEO Checklist](https://nuxtseo.com/learn-seo/checklist)
- [Pre-Launch Warmup](https://nuxtseo.com/learn-seo/pre-launch-warmup)
- [Backlinks & Authority](https://nuxtseo.com/learn-seo/backlinks)

### [Tools](https://nuxtseo.com/tools "SEO Tools")

- [Social Share Debugger](https://nuxtseo.com/tools/social-share-debugger)
- [Robots.txt Generator](https://nuxtseo.com/tools/robots-txt-generator)
- [Meta Tag Checker](https://nuxtseo.com/tools/meta-tag-checker)
- [HTML to Markdown](https://nuxtseo.com/tools/html-to-markdown)
- [XML Sitemap Validator](https://nuxtseo.com/tools/xml-sitemap-validator)
- [Schema.org Validator](https://nuxtseo.com/tools/schema-validator)
- [Keyword Research Pro](https://nuxtseo.com/tools/keyword-research)
- [SERP Analyzer Pro](https://nuxtseo.com/tools/serp-analyzer)
- [Domain Rankings Pro](https://nuxtseo.com/tools/domain-rankings)

Copyright © 2023-2026 Harlan Wilton - [MIT License](https://github.com/harlan-zw/nuxt-seo/blob/main/license) · [mdream](https://mdream.dev)