v3.0.0
Just want to dive in? Check out the ๐พ ย Playground.
๐ 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 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
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 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
In v2 we were limited to only twemoji
emojis (Twitter Emojis).
In v3 we switch to using the Iconify 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
PNGs are great for most use cases, but they come at the cost of a larger file size.
For Chromium based rendering, jpeg
images will now be rendered by default.
For Satori, you can now opt-in by adding a sharp
dependency and switching the extension to jpeg
.
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 ogImage
frontmatter key that can be used to configure your OG Image.
This will only work when you're using Document Driven mode, or you have set a path
.
---
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 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
Whenever you add a template has a <style>
block, we need to use the 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 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 /<path>/__og_image__/og.png
, this has been changed to /__og-image__/image/<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
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 fonts
prop on the defineOgImage
component.
defineOgImage({
fonts: [
'Noto+Sans:400'
]
})
See the Custom Fonts guide for more details.
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.
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 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).
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 prerender:config
hook (#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 dependencies.
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
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
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 NuxtSeo
, previously it was called Fallback
.
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 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,
},
},
})