nuxt-og-image

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.

Features

✨ Turn your Vue components into og:image templates
🎨 Design them in the OG Image Playground with full HMR
▲ Render using Satori: Tailwind classes, Google fonts, emoji support and more!
🤖 Or prerender using the Browser: Supporting painless, complex templates
📸 Feeling lazy? Just generate screenshots for every page: hide elements, wait for animations, and more
⚙️ Works on the edge: Vercel Edge and Cloudflare Workers

Demos

Install

# Install module
npm install --save-dev nuxt-og-image
# Using yarn
yarn add --dev nuxt-og-image

Setup

nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-og-image',
  ],
})

Requirements

This feature uses Nuxt Islands, which requires Nuxt >= 3.1.

Add your host name

The og:image meta tag requires the full URL, so you must provide your site host.

nuxt.config.ts

export default defineNuxtConfig({
  // Recommended
  runtimeConfig: {
    public: {
      siteUrl: process.env.NUXT_PUBLIC_SITE_URL || 'https://example.com',
    }
  },
  // OR
  ogImage: {
    host: 'https://example.com',
  },
})

Guides

Your first Satori `og:image`

For this guide, you will create your Satori OG image using the default component for your home page.

1. Define a static OG Image

Within your pages/index.vue, use defineOgImageStatic or OgImageStatic to define your og:image component.

Make sure you have defined some metadata as props will be inferred from it.

<script lang="ts" setup>
// 1. make sure you have some meta
useSeoMeta({
  title: 'Home',
  description: 'My awesome home page.',
})
// 2a. Use the Composition API
defineOgImageStatic()
</script>

<template>
  <div>
    <!-- 2b. OR Component API -->
    <OgImageStatic />
  </div>
</template>

2. View your `og:image`

Appending /__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 http://localhost:3000, you can view your og:image at http://localhost:3000/__og_image__.

3. Customize your `og:image`

While 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!',
  background: 'lightblue'
})
</script>

Congrats, you've set up your first Satori og:image! You can checkout the options of the default template.

Making your own Satori template

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.

1. Create an island component

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>

2. Use the new 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.

3. Customize your template

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.

Using Satori

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:

Tailwind classes (Note: Satori Tailwind support is experimental, not all classes are supported)
Google Fonts, default is Inter
Emoji support with Twemoji
Relative image support (you should link images from your public directory /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.

Taking screenshots

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>

Requirements

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"
  }
}

API

The module exposes a composition and component API to implement your og:image generation. You should pick whichever one you prefer using.

OgImageStatic / defineOgImageStatic

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.

Example

<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>

OgImageDynamic / defineOgImageDynamic

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.

Example

<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"
    :dynamic-data="dynamicData"
  />
</template>

OgImageOptions

`alt`

Type: string
Default: ''
Required: false

The og:image:alt attribute for the image. It should describe the contents of the image.

`height`

Type: number
Default: 630
Required: true

The height of the screenshot. Will be used to generate the og:image:height meta tag.

`width`

Type: number
Default: 1200
Required: true

The width of the screenshot. Will be used to generate the og:image:width meta tag.

`component`

Type: string
Default: OgImageBasic
Required: true

The name of the component to use as the template. By default, it uses OgImageBasic provided by the module.

`provider`

Type: string
Default: satori
Required: false

The provider to use to generate the image. The default provider is satori. When you use browser it will use Puppeteer to generate the image.

`prerender`

Type: boolean
Default: true when static, false when dynamic

OgImageScreenshot / defineOgImageScreenshot

The OgImageScreenshot component and the defineOgImageScreenshot composable creates a screenshot of a page using a browser.

The options follow the ScreenshotsOptions interface.

Example

<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>

ScreenshotsOptions

This interface extends the OgImageOptions.

`colorScheme`

Type: 'dark' | 'light'
Default: light
Required: false

The color scheme to use when generating the image. This is useful for generating dark mode images.

defineOgImageScreenshot({
  colorScheme: 'dark'
})

`delay`

Type: number
Default: 0
Required: false

The 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
})

`mask`

Type: string
Default: undefined
Required: false

HTML 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'
})

`selector`

Type: string
Default: undefined
Required: false

The selector to take a screenshot of. This is useful if you want to exclude header / footer elements.

defineOgImageScreenshot({
  selector: '.page-content'
})

Module Config

`host`

Type: string
Default: undefined
Required: true

The host of your site. This is required to generate the absolute path of the og:image.

`defaults`

Type: OgImageOptions
Default: { component: 'OgImageBasic', width: 1200, height: 630, }
Required: false

The default options to use when generating images.

`forcePrerender`

Type: boolean
Default: false
Required: false

This 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`

Type: ``${string}:${number}[]
Default: ['Inter:400', 'Inter:700']
Required: false

Fonts 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']
  }
})

`satoriOptions`

Type: SatoriOptions
Default: {}
Required: false

Options to pass to Satori when generating images. See the Satori docs.

`experimentalNitroBrowser` (experimental)

Type: boolean
Default: false
Required: false

In 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.

nuxt-og-image

nuxt-og-image

Features

Demos

Install

Setup

Requirements

Add your host name

Guides

Your first Satori og:image

1. Define a static OG Image

2. View your og:image

3. Customize your og:image

Making your own Satori template

1. Create an island component

2. Use the new template

3. Customize your template

Using Satori

Taking screenshots

Requirements

API

OgImageStatic / defineOgImageStatic

Example

OgImageDynamic / defineOgImageDynamic

Example

OgImageOptions

alt

height

width

component

provider

prerender

OgImageScreenshot / defineOgImageScreenshot

Example

ScreenshotsOptions

colorScheme

delay

mask

selector

Module Config

host

defaults

forcePrerender

fonts

satoriOptions

experimentalNitroBrowser (experimental)

Examples

Sponsors

Credits

License

Keywords

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Your first Satori `og:image`

2. View your `og:image`

3. Customize your `og:image`

`alt`

`height`

`width`

`component`

`provider`

`prerender`

`colorScheme`

`delay`

`mask`

`selector`

`host`

`defaults`

`forcePrerender`

`fonts`

`satoriOptions`

`experimentalNitroBrowser` (experimental)

Weekly Downloads