nuxt-og-image
Advanced tools
Enlightened OG Image generation for Nuxt 3.
|
Status: v1 Released Please report any issues 🐛 Made possible by my Sponsor Program 💖 Follow me @harlan_zw 🐦 • Join Discord for help |
ℹ️ Looking for a complete SEO solution? Check out nuxt-seo-kit.
og:image in the OG Image Playground with full HMR# Install module
npm install --save-dev nuxt-og-image
# Using yarn
yarn add --dev nuxt-og-image
nuxt.config.ts
export default defineNuxtConfig({
modules: [
'nuxt-og-image',
],
})
This feature uses Nuxt Islands, which requires Nuxt 3.0.1.
If you're using Nuxt 3.0.0, you will need to switch to the edge-release channel.
The og:image meta tag requires the full URL, so you must provide your site host.
nuxt.config.ts
export default defineNuxtConfig({
// Recommended
runtimeConfig: {
siteUrl: 'https://example.com',
},
// OR
ogImage: {
host: 'https://example.com',
},
})
og:imageFor this guide, you will create your Satori OG image using the default component for your home page.
Within your pages/index.vue, use defineOgImageStatic or OgImageStatic to define your og:image component.
Make sure you have defined some metadata for your page with useHead as props will be inferred from it.
<script lang="ts" setup>
// 1. make sure you have some meta
useHead({
title: 'Home',
meta: [
{ name: 'description', content: 'My awesome home page.' },
],
})
// 2a. Use the Composition API
defineOgImageStatic()
</script>
<template>
<div>
<!-- 2b. OR Component API -->
<OgImageStatic />
</div>
</template>
og:imageAppending /__og_image__ to the end of the URL will show you the playground for that pages og:image. This provides
a live preview of your og:image and allows you to edit it in real-time.
For example, if your local site is hosted at https://localhost:3000, you can view your og:image at https://localhost:3000/__og_image__.
You should see something like the following:
og:imageWhile you have the playground open, start customising the OG Image by providing options to the defineOgImageStatic function.
<script lang="ts" setup>
defineOgImageStatic({
title: 'Welcome to my site!'
})
</script>
Congrats, you've set up your first Satori og:image!
Templates for OG images are powered by Nuxt Islands, which are just Vue components. In this guide we'll create a new
template and use it for our og:image.
Make a folder in your components directory called islands.
Within this directory make a new component called MyOgImage.vue,
you can use the following template to begin:
<script setup lang="ts">
const props = defineProps({
title: String,
})
</script>
<template>
<div class="w-full h-full flex text-white bg-blue-500 items-center justify-center">
<h1 :style="{ fontSize: '70px' }">{{ title }} 👋</h1>
</div>
</template>
Now that you have your template, you can use it in for your defineOgImageStatic function.
<script lang="ts" setup>
defineOgImageStatic({
component: 'MyOgImage',
title: 'Welcome to my site!'
})
</script>
View this image in your browser by appending /__og_image__ to the end of the URL.
Now that you have your template, you can start customizing it.
Any options you pass to the defineOgImageStatic composable will be available in the component. With this in mind, we can
add support for changing the background color.
<script setup lang="ts">
const props = defineProps({
title: String,
backgroundColor: String
})
</script>
<template>
<div :class="[backgroundColor]" class="w-full h-full flex text-white items-center justify-center">
<h1 :style="{ fontSize: '70px' }">{{ title }} 👋</h1>
</div>
</template>
Now let's customise the background to be green instead.
<script lang="ts" setup>
defineOgImageStatic({
component: 'MyOgImage',
title: 'Welcome to my site!',
backgroundColor: 'bg-green-500'
})
</script>
Within the playground, you should now see the background color change to green.
It's important to familiarize yourself with Satori before you make more complex templates.
Satori has limited capacity for rendering styles; you should reference which ones are available within their documentation.
Out of the box, this module provides support for the following:
/my-image.png)If you find Satori is too limiting for your needs, you can always use the browser provider to capture browser screenshots instead.
If you want to simply take a screenshot of your page, you can use the OgImageScreenshot component or defineOgImageScreenshot composable.
<script lang="ts" setup>
defineOgImageScreenshot()
</script>
Alternatively you can pass the { provider: 'browser' } option to defineOgImageStatic.
<script lang="ts" setup>
defineOgImageStatic({
component: 'MyAwesomeOgImage',
// this will take a browser screenshot
provider: 'browser'
})
</script>
If you don't have a chromium binary installed on your system, run npx playwright install.
If you are using this module in a CI context and the images aren't being generated, you may need to install a chromium binary.
You can do this by running npx playwright install within your build command.
package.json
{
"scripts": {
"build": "npx playwright install && nuxt build"
}
}
The module exposes a composition and component API to implement your og:image generation. You should pick
whichever one you prefer using.
The OgImageStatic component and the defineOgImageStatic composable creates a static image
that will be pre-rendered.
The options follow the OgImageOptions interface,
any additional options will be passed to the component as props.
It is useful for images that do not change at runtime.
<script setup lang="ts">
// a. Composition API
defineOgImageStatic({
component: 'MyOgImageTemplate',
title: 'Hello world',
theme: 'dark'
})
</script>
<template>
<!-- b. Component API -->
<OgImageStatic
component="MyOgImageTemplate"
title="Hello world"
theme="dark"
/>
</template>
The OgImageDynamic component and the defineOgImageDynamic composable creates a dynamic image. They are not pre-rendered and will
be generated at runtime.
The options follow the OgImageOptions interface,
any additional options will be passed to the component as props.
This feature is not compatible with static sites built using nuxi generate.
<script setup lang="ts">
const dynamicData = await fetch('https://example.com/api')
// a. Composition API
defineOgImageDynamic({
component: 'MyOgImageTemplate',
title: 'Hello world',
dynamicData,
})
</script>
<template>
<!-- b. Component API -->
<OgImageDynamic
component="MyOgImageTemplate"
title="Hello world"
:dynamicData="dynamicData"
/>
</template>
altstring''falseThe og:image:alt attribute for the image. It should describe the contents of the image.
heightnumber630trueThe height of the screenshot. Will be used to generate the og:image:height meta tag.
widthnumber1200trueThe width of the screenshot. Will be used to generate the og:image:width meta tag.
componentstringOgImageBasictrueThe name of the component to use as the template. By default, it uses OgImageBasic provided by the module.
providerstringsatorifalseThe provider to use to generate the image. The default provider is satori.
When you use browser it will use Puppeteer to generate the image.
prerenderbooleantrue when static, false when dynamicThe OgImageScreenshot component and the defineOgImageScreenshot composable creates a screenshot of a page using a browser.
The options follow the ScreenshotsOptions interface.
<script setup lang="ts">
// a. Composition API
defineOgImageScreenshot({
// wait for animations
delay: 1000,
})
</script>
<template>
<!-- b. Component API -->
<OgImageScreenshot
url="https://example.com"
title="Hello world"
theme="dark"
/>
</template>
This interface extends the OgImageOptions.
colorScheme'dark' | 'light'lightfalseThe color scheme to use when generating the image. This is useful for generating dark mode images.
defineOgImageScreenshot({
colorScheme: 'dark'
})
delaynumber0falseThe delay to wait before taking the screenshot. This is useful if you want to wait for animations to complete.
defineOgImageScreenshot({
// wait 2 seconds
delay: 2000
})
maskstringundefinedfalseHTML selectors that should be removed from the image. Useful for removing popup banners or other elements that may be in the way.
defineOgImageScreenshot({
mask: '.popup-banner, .cookie-banner'
})
selectorstringundefinedfalseThe selector to take a screenshot of. This is useful if you want to exclude header / footer elements.
defineOgImageScreenshot({
mask: '.page-content'
})
hoststringundefinedtrueThe host of your site. This is required to generate the absolute path of the og:image.
defaultsOgImageOptions{ component: 'OgImageBasic', width: 1200, height: 630, }falseThe default options to use when generating images.
forcePrerenderbooleanfalsefalseThis is enabled when you run nuxi generate. It forces all OG images to be pre-rendered as the server is not available to generate
runtime images.
fonts[]['Inter:400', 'Inter:700']falseFonts families to use when generating images with Satori. When not using Inter it will automatically fetch the font from Google Fonts.
For example, if you wanted to add the Roboto font, you would add the following:
export default defineNuxtConfig({
ogImage: {
fonts: ['Roboto:400', 'Roboto:700']
}
})
satoriOptionsSatoriOptions{}falseOptions to pass to Satori when generating images. See the Satori docs.
experimentalNitroBrowser (experimental)booleanfalsefalseIn a server runtime, the default behaviour is to generate images using Satori. If you'd like to generate runtime images using the a browser instance for screenshots, you can enable this setting.
This is experimental and may not work in all environments.
MIT License © 2023-PRESENT Harlan Wilton
FAQs
Enlightened OG Image generation for Nuxt.
The npm package nuxt-og-image receives a total of 32,716 weekly downloads. As such, nuxt-og-image popularity was classified as popular.
We found that nuxt-og-image demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Malicious PyPI package ‘set-utils’ steals Ethereum private keys by exfiltrating them through blockchain transactions via the Polygon RPC.
Research
Security News
Malicious Go packages are impersonating popular libraries to install hidden loader malware on Linux and macOS, targeting developers with obfuscated payloads.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.