Caching Images

In cases where you need to generate images at runtime, Nuxt OG Image provides a caching layer to reduce the load on your server.

This caching layer uses SWR caching is enabled by default with a cache time of 72 hours.

Build Cache (CI Persistence)

For CI/CD environments, you can enable persistent build caching to avoid regenerating images between deployments when the output would be identical.

export default defineNuxtConfig({
  ogImage: {
    buildCache: true
  }
})

This stores rendered images in node_modules/.cache/nuxt-seo/og-image/ during prerendering. The cache automatically invalidates when:

• Options change - Different title, description, or other props
• Template changes - The component file is modified
• Module version changes - You upgrade nuxt-og-image

Automatic Cleanup

After each prerender, orphaned cache files (images no longer generated) are automatically cleaned up if they're older than 7 days. This prevents unbounded cache growth while preserving images that social platforms may still be referencing.

CI Configuration

To persist the cache between CI runs, add the cache directory to your CI configuration:

- name: Cache OG Images
  uses: actions/cache@v4
  with:
    path: node_modules/.cache/nuxt-seo
    key: og-images-${{ github.ref_name }}

cache:
  paths:
    - node_modules/.cache/nuxt-seo/

Custom Cache Directory

You can customize the cache location:

export default defineNuxtConfig({
  ogImage: {
    buildCache: {
      base: '.cache/og-image'
    }
  }
})

Runtime Cache Storage

Nitro caching by default will use the memory as a cache storage. This means that if you restart your server, the cache will be cleared.

It's recommended to set a persistent cache storage. This can be done using the runtimeCacheStorage option.

The option takes the same configuration as the Nuxt nitro.storage option. See the Nitro Storage Layer documentation for more details.

For example:

export default defineNuxtConfig({
  ogImage: {
    // cloudflare kv binding example, set your own config
    runtimeCacheStorage: {
      driver: 'cloudflare-kv-binding',
      binding: 'OG_IMAGE_CACHE'
    }
  }
})

Using Runtime Config

If you need to configure the cache storage with runtime environment variables (e.g., for different Redis hosts per environment), you can mount your own storage driver and reference it by key.

export default defineNuxtConfig({
  ogImage: {
    // Reference your own storage mount by key
    runtimeCacheStorage: 'og-image-cache'
  }
})

Then mount the storage in a Nitro plugin where you have access to runtime config:

import redisDriver from 'unstorage/drivers/redis'

export default defineNitroPlugin(() => {
  const config = useRuntimeConfig()

  const driver = redisDriver({
    base: 'og-image',
    host: config.redis.host,
    port: config.redis.port,
    password: config.redis.password,
  })

  useStorage().mount('og-image-cache', driver)
})

This approach lets you:

• Use environment variables for connection details
• Share a single Redis connection across multiple features
• Configure the driver dynamically at runtime

Cache Time

You can change the cache time of an image by providing cacheMaxAgeSeconds in milliseconds when defining the image.

defineOgImage({
  cacheMaxAgeSeconds: 30 // 30 seconds
})

Alternatively, you can change the default cache time in your nuxt.config.

export default defineNuxtConfig({
  ogImage: {
    defaults: {
      cacheMaxAgeSeconds: 60 * 60 * 24 * 7 // 7 days
    }
  }
})

Query Parameters

By default, query parameters are ignored when generating cache keys. This means /page and /page?ref=twitter share the same cache entry.

If your OG images depend on query parameters, you can include them in the cache key:

export default defineNuxtConfig({
  ogImage: {
    cacheQueryParams: true
  }
})

Custom Cache Key

For full control over caching, you can provide a custom cache key:

defineOgImage({
  cacheKey: 'my-custom-key'
})

This is useful when you need to cache based on specific criteria that aren't part of the URL.

Cache Version

By default, the cache is namespaced with the module version. This means upgrading nuxt-og-image will invalidate all cached images.

To persist cache across module upgrades, set a static cacheVersion or disable it entirely:

export default defineNuxtConfig({
  ogImage: {
    cacheVersion: 'v1',
  }
})

export default defineNuxtConfig({
  ogImage: {
    cacheVersion: false // no version namespace
  }
})

This is useful for production deployments where you want to control cache invalidation manually.

Purging the cache

If you need to purge the cache, you can do so by visiting the OG Image URL appended with a ?purge query param.

For example, to purge the OG Image cache for this page you could append ?purge to the OG image URL shown in the meta tags.

Bypassing the cache

While not recommended, if you prefer to opt-out of caching, you can do so by providing a 0 second cacheMaxAgeSeconds or disabling runtimeCacheStorage.

<script lang="ts" setup>
defineOgImage({
  cacheMaxAgeSeconds: 0 // disable at an individual image level
})
</script>

export default defineNuxtConfig({
  ogImage: {
    // disable at a global level
    runtimeCacheStorage: false,
  }
})