fix: burst cache when og image templates change

harlan-zw · harlan-zw · commit 0b81718651c3 · 2026-03-26T18:02:11.000+11:00
diff --git a/src/runtime/app/utils.ts b/src/runtime/app/utils.ts
@@ -174,15 +174,22 @@ export function getOgImagePath(_pagePath: string, _options?: Partial<OgImageOpti
   const { defaults } = useOgImageRuntimeConfig()
   const extension = _options?.extension || defaults?.extension || 'png'
   const isStatic = import.meta.prerender
+  const options: Record<string, any> = { ..._options, _path: _pagePath }
+  // Include the component template hash so that template changes produce different URLs,
+  // busting CDN/build caches (Vercel, social platform crawlers like Twitter/Facebook, etc.)
+  const componentName = _options?.component || defaults?.component || componentNames?.[0]?.pascalName
+  const component = componentNames?.find((c: any) => c.pascalName === componentName || c.kebabName === componentName)
+  if (component?.hash)
+    options._componentHash = component.hash
   // Build URL with encoded options (Cloudinary-style)
   // Include _path so the server knows which page to render
   // Pass defaults to skip encoding default values in URL
-  const result = buildOgImageUrl({ ..._options, _path: _pagePath }, extension, isStatic, defaults)
-  let path = joinURL('/', baseURL, result.url)
   // For dynamic images, append build ID to bust external platform caches (Telegram, Facebook, etc.)
   if (!isStatic && runtimeConfig.app.buildId) {
     path = withQuery(path, { _v: runtimeConfig.app.buildId })
   }
+  const result = buildOgImageUrl(options, extension, isStatic, defaults)
+  const path = joinURL('/', baseURL, result.url)
   return {
     path,
     hash: result.hash,
diff --git a/src/runtime/server/og-image/context.ts b/src/runtime/server/og-image/context.ts
@@ -115,8 +115,10 @@ export async function resolveContext(e: H3Event): Promise<H3Error | OgImageRende
 
   // basePath is used for route rules matching - can be provided via _path param
   const basePath = withoutTrailingSlash(urlOptions._path || '/')
+  const componentHash = urlOptions._componentHash || ''
   delete urlOptions._path
   delete urlOptions._hash // Remove internal hash field
+  delete urlOptions._componentHash // Not needed for rendering
 
   const basePathWithQuery = queryParams._query && typeof queryParams._query === 'object'
     ? withQuery(basePath, queryParams._query)
@@ -146,8 +148,10 @@ export async function resolveContext(e: H3Event): Promise<H3Error | OgImageRende
   const rendererType = normalised.renderer
   // In hash mode, basePath is always '/' (since _path isn't in the prerender cache payload),
   // so use the options hash directly as cache key to avoid all hash-mode images sharing one cache entry.
-  const key = normalised.options.cacheKey
+  // Component hash is appended so template changes invalidate the runtime cache.
+  const baseCacheKey = normalised.options.cacheKey
     || (hashMatch ? `hash:${hashMatch[1]}` : resolvePathCacheKey(e, basePathWithQuery, runtimeConfig.cacheQueryParams))
+  const key = componentHash ? `${baseCacheKey}:${componentHash}` : baseCacheKey
 
   let renderer: ((typeof SatoriRenderer | typeof BrowserRenderer | typeof TakumiRenderer) & { __mock__?: true }) | undefined
   switch (rendererType) {
diff --git a/src/runtime/server/utils.ts b/src/runtime/server/utils.ts
@@ -1,5 +1,6 @@
 import type { H3Event } from 'h3'
-import type { OgImageOptions, OgImageRuntimeConfig } from '../types'
+import type { OgImageComponent, OgImageOptions, OgImageRuntimeConfig } from '../types'
+import { componentNames } from '#og-image-virtual/component-names.mjs'
 import { useRuntimeConfig } from 'nitropack/runtime'
 import { joinURL } from 'ufo'
 import { buildOgImageUrl } from '../shared'
@@ -14,9 +15,16 @@ export function getOgImagePath(_pagePath: string, _options?: Partial<OgImageOpti
   const { defaults } = useOgImageRuntimeConfig()
   const extension = _options?.extension || defaults.extension
   const isStatic = import.meta.prerender
+  const options: Record<string, any> = { ..._options, _path: _pagePath }
+  // Include the component template hash so that template changes produce different URLs,
+  // busting CDN/build caches (Vercel, social platform crawlers like Twitter/Facebook, etc.)
+  const componentName = _options?.component || defaults.component || (componentNames as OgImageComponent[])?.[0]?.pascalName
+  const component = (componentNames as OgImageComponent[])?.find(c => c.pascalName === componentName || c.kebabName === componentName)
+  if (component?.hash)
+    options._componentHash = component.hash
   // Include _path so the server knows which page to render
   // Pass defaults to skip encoding default values in URL
-  const result = buildOgImageUrl({ ..._options, _path: _pagePath }, extension, isStatic, defaults)
+  const result = buildOgImageUrl(options, extension, isStatic, defaults)
   return {
     path: joinURL('/', baseURL, result.url),
     hash: result.hash,
diff --git a/src/runtime/shared/urlEncoding.ts b/src/runtime/shared/urlEncoding.ts
@@ -46,6 +46,7 @@ const PARAM_ALIASES: Record<string, string> = {
   cache: 'cacheMaxAgeSeconds',
   p: '_path', // page path - needs alias since _path starts with underscore
   q: '_query', // query params - needs alias since _query starts with underscore
+  ch: '_componentHash', // component template hash for cache busting prerendered URLs
 }
 
 // Reverse mapping (param name -> alias)
@@ -75,6 +76,7 @@ const KNOWN_PARAMS = new Set([
   'fonts',
   '_query',
   '_hash',
+  '_componentHash',
   'socialPreview',
   'props',
   '_path',
diff --git a/test/unit/urlEncoding.test.ts b/test/unit/urlEncoding.test.ts
@@ -393,6 +393,51 @@ describe('urlEncoding', () => {
     })
   })
 
+  describe('_componentHash cache busting', () => {
+    it('encodes _componentHash as ch alias', () => {
+      const encoded = encodeOgImageParams({ props: { title: 'Hello' }, _componentHash: 'abc123' })
+      expect(encoded).toContain('ch_abc123')
+      expect(encoded).toContain('title_Hello')
+    })
+
+    it('different _componentHash produces different URL', () => {
+      const url1 = buildOgImageUrl({ props: { title: 'Hello' }, _componentHash: 'hash1' }, 'png', true)
+      const url2 = buildOgImageUrl({ props: { title: 'Hello' }, _componentHash: 'hash2' }, 'png', true)
+      expect(url1.url).not.toBe(url2.url)
+    })
+
+    it('same _componentHash produces same URL', () => {
+      const url1 = buildOgImageUrl({ props: { title: 'Hello' }, _componentHash: 'hash1' }, 'png', true)
+      const url2 = buildOgImageUrl({ props: { title: 'Hello' }, _componentHash: 'hash1' }, 'png', true)
+      expect(url1.url).toBe(url2.url)
+    })
+
+    it('decodes _componentHash as known param (not as prop)', () => {
+      const encoded = encodeOgImageParams({ props: { title: 'Hello' }, _componentHash: 'abc123' })
+      const decoded = decodeOgImageParams(encoded)
+      expect(decoded._componentHash).toBe('abc123')
+      expect(decoded.props?.ch).toBeUndefined()
+      expect(decoded.props?._componentHash).toBeUndefined()
+    })
+
+    it('_componentHash affects hash mode URLs too', () => {
+      const longTitle = 'A'.repeat(250)
+      const opts1 = { props: { title: longTitle }, _componentHash: 'hash1' }
+      const opts2 = { props: { title: longTitle }, _componentHash: 'hash2' }
+      const result1 = buildOgImageUrl(opts1, 'png', true)
+      const result2 = buildOgImageUrl(opts2, 'png', true)
+      expect(result1.hash).toBeDefined()
+      expect(result2.hash).toBeDefined()
+      expect(result1.hash).not.toBe(result2.hash)
+    })
+
+    it('_componentHash included in hashOgImageOptions (not excluded like _path)', () => {
+      const hash1 = hashOgImageOptions({ width: 1200, _componentHash: 'hash1' })
+      const hash2 = hashOgImageOptions({ width: 1200, _componentHash: 'hash2' })
+      expect(hash1).not.toBe(hash2)
+    })
+  })
+
   describe('non-ASCII encode/decode roundtrip', () => {
     function roundtrip(props: Record<string, any>) {
       const encoded = encodeOgImageParams({ props })
