v3.0.0
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
✨ 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 guide for more information.
⛹️ 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 (Chromium, Satori) and more.
- 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!
- 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
In v2, you had to define your config using
In v3, you can now define your config using
defineOgImageComponent(
// component name
'NuxtSeo',
// component props
{ title: 'Hello!' },
// image options
{ alt: 'A welcome message' }
)
🍃 UnoCSS and Theming Support
Satori itself provides a subset of Tailwind CSS 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, loaded with your Tailwind / UnoCSS 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
<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
In v2 we were limited to only
In v3 we switch to using the Iconify API which gives us access to the following emoji families:
The default emoji family has been switched to
🖼️ JPEG OG Images
PNGs are great for most use cases, but they come at the cost of a larger file size.
For Chromium based rendering,
For Satori, you can now opt-in by adding a
See the JPEGs guide for more information.
📝 Nuxt Content integration
Using a component or composable with within your markdown content is a bit awkward.
With v3 the module now supports the
---
path: /blog/3-months-of-europe
ogImage:
component: BlogOgImage
props:
image: /blog/3-months-of-europe.png
readingMins: 5
---
🔄 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
For example, this documentation website uses it to set the
export default defineNuxtConfig({
routeRules: {
'/og-image/**': {
ogImage: {
props: { icon: 'carbon:image-search' }
}
}
}
})
Improved css-inline Compatibility
Whenever you add a template has a
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 this won't be enabled 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
New OG Image URL
The old pattern for OG images was
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
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
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
defineOgImage({
fonts: [
'Noto+Sans:400'
]
})
See the Custom Fonts guide for more details.
Updated Default Template
The default template is now called
It introduces a number of new props:
colorMode -light ,dark
Changes from a light or dark background / text color. Integrates with
theme -#${string}
Change the hex color of the flare and the Nuxt SEO logo.
Learn more on the NuxtSeo Template docs.
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 a bit of a mess with many configuration options.
In v3, the caching has been simplified to a single prop called
While not recommended, you can disable the caching by providing
Additionally, 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
With the introduction of the Nitro
This also means that if you're generating your app with
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
defineOgImage({ url: 'https://example.com/og.png' })
Simple HTML OG Images
If you want to simplify your integration, you can provide raw HTML to the
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
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
Trying to migrate? Check the v2 to v3 migration guide.
Nuxt Config
playground has been removed, if you have Nuxt DevTools enabled then the playground will always be enabledruntimeBrowser has been removedruntimeSatori has been removed
Nuxt Hooks
og-image:prerenderScreenshots is no longer supportedog-image:config has been removed
OG Image Options
provider renamed torenderer , thebrowser provider is nowchromium cacheTtl renamed tocacheMaxAgeSeconds cache ,cacheKey ,static are removed- You can no longer pass non-typed keys, you should provide props to the
props key or usedefineOgImageComponent .
The default template is now called
Composables
The following composables have been removed:
defineOgImageStatic defineOgImageDynamic defineOgImageCached defineOgImageWithoutCache
Components
The following components have been removed:
OgImageStatic OgImageDynamic OgImageCached OgImageWithoutCache
The remaining components
export default defineNuxtConfig({
ogImage: {
componentOptions: {
global: true,
},
},
})