nuxt-og-image

nuxt-og-image

Generate dynamic social share images for you Nuxt v3 app.

Status: 🤫 Early Access - Active Development 🤫 Please report any issues 🐛 Made possible by my Sponsor Program 💖 Follow me @harlan_zw 🐦 • Join Discord for help

Features

• 🧙 Generate images for your entire site in minutes with minimal config
• 🎨 Build your own template with Vue (powered by Nuxt Islands)
• 📸 OR just generates page screenshots
• 📦 Composable and component API

Install

⚠️ This module is still in development. Please get in touch with me over Twitter or Discord if you are going to attempt to use this.

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

Chromium Dependency

By default, this module does not install chromium binaries for you, instead relying on locally installed chrome.

If you want to use this module in a CI or SSR environment, you will need the binaries.

You can either use puppeteer or chrome-aws-lambda.

npm install --save-dev puppeteer # or chrome-aws-lambda

Setup

nuxt.config.ts

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

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: {
    siteUrl: 'https://example.com',
  },
  // OR
  ogImage: {
    host: 'https://example.com',
  },
})

Pre-render routes

While the module is in early access, you should ensure that you pre-render any pages you want to generate images for.

export default defineNuxtConfig({
  nitro: {
    prerender: {
      crawlLinks: true,
      routes: [
        '/',
        // any URLs that can't be discovered by crawler
        '/my-hidden-url'
      ]
    }
  }
})

Recommended: Enable Nuxt Islands

To be able to preview the image in development and generate template images, you'll need to enable Nuxt Islands.

If you're using Nuxt 3.0.0, you will need to switch to the edge-release channel.

Once that's done, you can enable the flag for islands.

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    componentIslands: true
  },
})

Generating Screenshots

Your page / app.vue / layout

<script lang="ts" setup>
// Choose either Composition API
defineOgImageScreenshot()
</script>
<template>
  <div>
    <!-- OR Component API -->
    <OgImageScreenshot />
  </div>
</template>

Generating Template Images

The template image generator is powered by Nuxt Islands. This means that you can use any Vue component you want to generate your images.

Your page / app.vue / layout

<script lang="ts" setup>
// Choose either Composition API
defineOgImage({
  component: 'OgImageTemplate', // Nuxt Island component
  // pass in any custom props
  myCustomTitle: 'My Title'
})
</script>
<template>
  <div>
    <!-- OR Component API -->
    <OgImage component="OgImageTemplate" my-custom-title="My Title" />
  </div>
</template>

Creating your own template

Create a new component with .island.vue as the suffix, such as components/Banner.island.vue.

Use the below template to test it works, then modify it how you like.

<script setup lang="ts">
const props = defineProps({
  // these will always be provided
  path: String,
  title: String,
  description: String,
  // anything custom comes here
  backgroundImage: String
})
</script>

<template>
  <div class="wrap">
    <div>
      <h1>
        {{ title }}
      </h1>
      <p>{{ description }}</p>
    </div>
  </div>
</template>

<style scoped>
.wrap {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  color: white;
  background: linear-gradient(to bottom, #30e8bf, #ff8235);
}

h1 {
  font-size: 4rem;
}
</style>

Make sure you reference this component when using defineOgImage and any props to pass.

<script lang="ts" setup>
defineOgImage({
  component: 'Banner', 
  backgroundImage: 'https://example.com/my-background-image.jpg',
})
</script>

Previewing Images

Once you have defined the og:image using the composable, you can preview the image by visiting the following URLs:

• /your-path/__og-image Renders the HTML output
• /your-path/og-image.png Renders the og:image

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.

runtimeImages

• Type: boolean
• Default: process.dev

Allows you to generate images at runtime in production. This uses a headless browser to generate images and may have deployment issues.

Examples

• Unhead Docs

Sponsors

Credits

• Pooya Parsa Kachick
• Nuxt Team

License

MIT License © 2022-PRESENT Harlan Wilton