v5 to v6 · 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) Migration Guides # v5 to v6 [Copy for LLMs](https://nuxtseo.com/docs/og-image/migration-guide/v6.md) ## [Quick Migration](#quick-migration) Run the migration CLI to automate most changes: ``` # Rename components and migrate API calls npx nuxt-og-image migrate v6 # Preview changes without applying (dry run) npx nuxt-og-image migrate v6 --dry-run ``` This will: - Rename `components/OgImage/*.vue` to include renderer suffix (defaults to `.takumi.vue`) - Migrate `defineOgImageComponent()` calls to `defineOgImage()` ## [What's New](#whats-new) - **Takumi as recommended renderer** - [Takumi](https://takumi.kane.tw) is 2-10x faster than Satori with the same feature set - **First-class CSS support** - Tailwind v4, [UnoCSS](https://unocss.dev), CSS variables, and Nuxt UI v3 colors all work - **Redesigned DevTools** - better debugging, Bluesky social card support, more accessible interface - **Multiple OG images per page** - different dimensions for different platforms - **@nuxt/fonts integration** - custom fonts work if you install `@nuxt/fonts` - **Smarter caching** - CDN-friendly Cloudinary-style URLs, cleaner cache keys ## [High Impact Changes](#high-impact-changes) Changes that affect most users upgrading to v6. ### [Install Renderer Dependencies](#install-renderer-dependencies) Renderer dependencies (satori, resvg, takumi, playwright) are no longer bundled. You must install them explicitly based on your renderer and runtime. See [PR #415](https://github.com/nuxt-modules/og-image/pull/415). **Takumi (recommended):** ``` # Node.js npm i @takumi-rs/core # Edge runtimes npm i @takumi-rs/wasm ``` **Satori:** ``` # Node.js npm i satori @resvg/resvg-js # Edge runtimes (Cloudflare, Vercel Edge, etc.) npm i satori @resvg/resvg-wasm ``` **Browser:** ``` npm i playwright-core ``` Running `nuxi dev` will prompt you to install missing dependencies automatically. ### [Component Renderer Suffix Required](#component-renderer-suffix-required) OG Image components must now include a renderer suffix in their filename. See [PR #433](https://github.com/nuxt-modules/og-image/pull/433). ``` # Before (no longer works) components/OgImage/MyTemplate.vue # After components/OgImage/MyTemplate.satori.vue # for Satori renderer components/OgImage/MyTemplate.takumi.vue # for Takumi renderer components/OgImage/MyTemplate.browser.vue # for Browser renderer ``` This change enables: - Automatic renderer detection from filename - Multiple renderer variants of the same component - Tree-shaking of unused renderer code The CLI migration command will rename your components automatically: ``` npx nuxt-og-image migrate v6 ``` #### [Multiple Renderers Per Component](#multiple-renderers-per-component) You can now create renderer-specific variants of the same component: ``` components/OgImage/ MyTemplate.satori.vue # Satori version MyTemplate.takumi.vue # Takumi version (faster) ``` When calling `defineOgImage('MyTemplate')`, the module uses the first registered variant. To select a specific renderer, use dot notation (`'MyTemplate.takumi'`) or PascalCase (`'MyTemplateTakumi'`). The module removed the `defaults.renderer` config option and `renderer` option on `defineOgImage()`. The component filename suffix always determines the renderer. ### [Community Templates Must Be Ejected](#community-templates-must-be-ejected) Community templates (like `NuxtSeo`, `Brutalist`, `SimpleBlog`, etc.) are no longer bundled with production builds. If you're using a community template, you must eject it before building. See [PR #426](https://github.com/nuxt-modules/og-image/pull/426). ``` # List available templates npx nuxt-og-image list # Eject a specific template npx nuxt-og-image eject NuxtSeo ``` This copies the template to your `components/OgImage/` directory where it will be included in your build. **In development**, community templates continue to work without ejecting - they're loaded directly from the module. **In production**, only ejected templates are available. If you reference a community template that hasn't been ejected, you'll get an error. After ejecting, you can customize the template as needed. The ejected components are yours to modify. ## [Medium Impact Changes](#medium-impact-changes) Changes that affect users with specific configurations. ### [Fonts: @nuxt/fonts Integration](#fonts-nuxtfonts-integration) The module removed the `ogImage.fonts` config. `@nuxt/fonts` now handles fonts - install the module and your fonts work in OG images with no extra configuration. See [PR #432](https://github.com/nuxt-modules/og-image/pull/432). The module bundles Inter (400 and 700) as a zero-config fallback, so if you were only using Inter you can delete your font configuration entirely. ``` // Before export default defineNuxtConfig({ ogImage: { - fonts: ['Inter:400', 'Inter:700'] } }) // After (Inter only) — remove the config, it works by default // After (custom fonts) — just install @nuxt/fonts export default defineNuxtConfig({ + modules: ['@nuxt/fonts', 'nuxt-og-image'], + fonts: { + families: [ + { name: 'Roboto', weights: [400, 700], global: true } + ] + } }) ``` Install @nuxt/fonts: ``` npx nuxi module add @nuxt/fonts ``` ### [`` and `` Components Removed](#ogimage-and-ogimagescreenshot-components-removed) The module removed the `` and `` Vue components. Use the equivalent composables instead: ``` - + ``` ``` - + ``` The migration CLI handles this automatically. ### [`componentOptions` Config Removed](#componentoptions-config-removed) The module removed the `ogImage.componentOptions` config option since there are no longer any components to configure. ``` export default defineNuxtConfig({ ogImage: { - componentOptions: { global: true }, } }) ``` ### [Object Syntax with `url` Replaced by `useSeoMeta`](#object-syntax-with-url-replaced-by-useseometa) The `defineOgImage()` object syntax for pre-prepared images is no longer needed. Use `useSeoMeta()` directly instead - it works without any interference from the module. ``` - defineOgImage({ url: '/my-image.png', width: 1200, height: 600, alt: 'My Image' }) + useSeoMeta({ ogImage: '/my-image.png', ogImageWidth: 1200, ogImageHeight: 600, ogImageAlt: 'My Image' }) ``` The migration CLI handles this automatically. ### [`defineOgImageComponent` Deprecated](#defineogimagecomponent-deprecated) The `defineOgImageComponent()` composable is deprecated. Use `defineOgImage()` with the component name as the first argument. See [PR #433](https://github.com/nuxt-modules/og-image/pull/433). ``` - defineOgImageComponent('NuxtSeo', { title: 'Hello' }) + defineOgImage('NuxtSeo', { title: 'Hello' }) ``` The API is identical - remove "Component" from the function name. The migration CLI handles this automatically. ### [First-Class CSS Support](#first-class-css-support) Build-time CSS processing replaces the UnoCSS runtime transformer. Tailwind v4, UnoCSS, CSS variables, and Nuxt UI v3 colors all work by default with zero configuration. See [PR #430](https://github.com/nuxt-modules/og-image/pull/430). **What this means:** - **Tailwind v4** - build-time class extraction with Tailwind's CSS engine, `@theme` values work - **UnoCSS** - full UnoCSS support - **CSS Variables** - use your app's CSS custom properties directly in OG image templates - **Nuxt UI v3** - the module automatically resolves semantic colors (`primary`, `secondary`, etc.) #### [Native Tailwind v4 Support](#native-tailwind-v4-support) Nuxt OG Image has native Tailwind v4 support. The module extracts classes from your OG components at build time and compiles them with Tailwind's CSS engine. Zero-config - the module auto-detects your Tailwind setup whether you're using `@nuxtjs/tailwindcss` or Tailwind v4 with the [Vite](https://vite.dev) plugin. #### [Theme Customizations](#theme-customizations) The module automatically resolves custom theme values defined in `@theme`: assets/css/main.css ``` @import "tailwindcss"; @theme { --color-brand: #ff6600; --font-heading: "Inter", sans-serif; } ``` components/OgImage/MyTemplate.satori.vue ``` ``` #### [Nuxt UI v3 Color Support](#nuxt-ui-v3-color-support) When using `@nuxt/ui` v3, the module automatically resolves semantic colors (`primary`, `secondary`, etc.) from your `app.config.ts`: app.config.ts ``` export default defineAppConfig({ ui: { colors: { primary: 'indigo', secondary: 'violet' } } }) ``` components/OgImage/MyTemplate.satori.vue ``` ``` ## [Low Impact Changes](#low-impact-changes) Changes that affect users with specific edge cases or deprecated configurations. ### [Cache Key Changes](#cache-key-changes) Query parameters are no longer included in cache keys. Previously, `/page?foo=bar` and `/page?baz=qux` would generate separate cached images. Now they share the same cache. See [PR #427](https://github.com/nuxt-modules/og-image/pull/427). If your OG images depend on query parameters, enable them explicitly: ``` export default defineNuxtConfig({ ogImage: { cacheQueryParams: true // restore v5 behavior } }) ``` Or set a custom cache key per image: ``` defineOgImage('NuxtSeo', { title: 'Hello' }, { cacheKey: \`my-page-${route.query.variant}\` }) ``` #### [Cache Version Control](#cache-version-control) New `cacheVersion` option controls cache key namespacing: ``` export default defineNuxtConfig({ ogImage: { // Default: module version (cache invalidates on upgrade) cacheVersion: false // disable versioning entirely } }) ``` ### [URL Path Changes](#url-path-changes) OG Image URLs have been shortened and restructured. This only affects you if you have hardcoded OG image URLs. See [PR #305](https://github.com/nuxt-modules/og-image/pull/305). | v5 | v6 | | --- | --- | | `/__og-image__/image/` | `/_og/d/` | | `/__og-image__/static/` | `/_og/s/` | | `/__og-image__/font/` | Removed (fonts served directly from `/_fonts/` via @nuxt/fonts) | | `/__og-image__/debug.json` | `/_og/debug.json` | #### [New Cloudinary-style URL Encoding](#new-cloudinary-style-url-encoding) OG Image URLs now encode all options directly in the URL path using a Cloudinary/IPX-style format. This enables automatic CDN caching since the same options always produce the same URL. **v5 format:** ``` /_og/d/satori/og.png?width=1200&title=Hello%20World ``` **v6 format:** ``` /_og/s/w_1200,title_Hello+World,p_Ii9zYXRvcmki.png ``` Key changes: - Options are comma-separated in the URL path (not query params) - Known params use short aliases: `w` (width), `h` (height), `c` (component), `k` (key), etc. - Component props are flattened to top level: `title_Hello+World` - Complex values (fonts, query params) are base64 encoded - The module encodes the page path as `p_` #### [Hash Mode for Long URLs (Prerendered Only)](#hash-mode-for-long-urls-prerendered-only) When prerendering, if the encoded URL path exceeds 200 characters (filesystem limit is 255), the module automatically switches to hash mode: ``` /_og/s/o_1whacq.png ``` This typically happens with: - Long component props (e.g., lengthy descriptions) - Multiple custom fonts with base64-encoded configurations - Complex query parameters The hash is deterministic - the same options always produce the same hash. The module caches options by hash during prerendering for lookup when rendering the image. Hash mode URLs are not supported at runtime. If you have any hardcoded references to the old URL format, update them to use the return value of `defineOgImage()` which now returns an array of generated paths: ``` const [ogImageUrl] = defineOgImage('NuxtSeo', { title: 'About Us' }) ``` #### [Long Runtime URLs](#long-runtime-urls) Because all options are now self-contained in the URL, runtime URLs can become long when passing many props. In v5, the URL was short because the server re-fetched the page to discover the payload - v6 avoids this round trip for stability and caching, at the cost of longer URLs. See the [Performance](https://nuxtseo.com/docs/og-image/guides/performance) guide for strategies to reduce URL size, optimise component rendering, and configure caching for production. ### [Nuxt Content v2 Support Removed](#nuxt-content-v2-support-removed) The module no longer supports Nuxt Content v2. If you're using `@nuxt/content`, you must upgrade to v3 or later. See [PR #410](https://github.com/nuxt-modules/og-image/pull/410). The module removed the automatic `ogImage` frontmatter handling for Content v2. Use `defineOgImage()` in your page components instead. ``` // pages/[...slug].vue defineOgImage('NuxtSeo', { title: 'My Page' }) ``` ### [Config Options Removed](#config-options-removed) See [PR #410](https://github.com/nuxt-modules/og-image/pull/410). #### [`strictNuxtContentPaths` Removed](#strictnuxtcontentpaths-removed) This option was deprecated and has no effect in Nuxt Content v3. Remove it from your config: ``` export default defineNuxtConfig({ ogImage: { - strictNuxtContentPaths: true, } }) ``` #### [Chromium Renderer Renamed to Browser](#chromium-renderer-renamed-to-browser) The `chromium` renderer has been renamed to `browser` for clarity. Update your component suffixes and configuration: **Component files:** ``` # Rename component files mv MyTemplate.chromium.vue MyTemplate.browser.vue ``` **Configuration:** ``` export default defineNuxtConfig({ ogImage: { compatibility: { runtime: { - chromium: 'playwright', + browser: 'playwright', } } } }) ``` #### [Browser `node` Binding Removed](#browser-node-binding-removed) The module removed the deprecated `browser: 'node'` compatibility option. Use `'playwright'` instead: ``` export default defineNuxtConfig({ ogImage: { compatibility: { runtime: { - browser: 'node', + browser: 'playwright', } } } }) ``` #### [Cloudflare Browser Rendering Support](#cloudflare-browser-rendering-support) You can now use Cloudflare Browser Rendering for runtime screenshots on Cloudflare Workers/Pages: nuxt.config.ts ``` export default defineNuxtConfig({ ogImage: { browser: { provider: 'cloudflare', binding: 'BROWSER' } } }) ``` See the [Browser Renderer](https://nuxtseo.com/docs/og-image/renderers/browser#cloudflare-browser-rendering) docs for setup instructions. ### [Import Path Changes](#import-path-changes) See [PR #410](https://github.com/nuxt-modules/og-image/pull/410). #### [`#nuxt-og-image-utils` Alias Removed](#nuxt-og-image-utils-alias-removed) If you were importing from this legacy alias, update your imports: ``` - import { ... } from '#nuxt-og-image-utils' + import { ... } from '#og-image/shared' ``` #### [`useOgImageRuntimeConfig` Import Path](#useogimageruntimeconfig-import-path) The module removed the deprecated stub export from `#og-image/shared`. Import from the correct path: ``` - import { useOgImageRuntimeConfig } from '#og-image/shared' + import { useOgImageRuntimeConfig } from '#og-image/app/utils' ``` ### [Sharp JPEG Errors](#sharp-jpeg-errors) Previously, if Sharp failed to load for JPEG rendering, it would log an error and fall back to PNG silently. Now it throws an error. See [PR #410](https://github.com/nuxt-modules/og-image/pull/410). Ensure you properly install Sharp and your runtime supports it if you're using JPEG output. See the [Renderers](https://nuxtseo.com/docs/og-image/renderers) guide for details. [Edit this page](https://github.com/nuxt-modules/og-image/edit/main/docs/content/6.migration-guide/v6.md) [Markdown For LLMs](https://nuxtseo.com/docs/og-image/migration-guide/v6.md) Did this page help you? [v2 to v3 Migrate Nuxt OG Image v2 to Nuxt OG Image v3.](https://nuxtseo.com/docs/og-image/migration-guide/v3) [v6.0.0 Release notes for Nuxt OG Image v6.](https://nuxtseo.com/docs/og-image/releases/v6) On this page - [Quick Migration](#quick-migration) - [What's New](#whats-new) - [High Impact Changes](#high-impact-changes) - [Medium Impact Changes](#medium-impact-changes) - [Low Impact Changes](#low-impact-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)