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

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

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

<script lang="ts" setup>
defineOgImageScreenshot()
</script>
<template>
  <div>
    <!-- Your page / app.vue / layout -->
  </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.

<script lang="ts" setup>
defineOgImage({
  component: 'OgImage', // Nuxt Island component
  // pass in any custom props
  myCustomTitle: 'My Title'
})
</script>
<template>
  <div>
    <!-- Your page / app.vue / layout -->
  </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.

Sponsors

Credits

• Pooya Parsa Kachick
• Nuxt Team

License

MIT License © 2022-PRESENT Harlan Wilton