fix(blog): resolve blog author avatars at build time (#1879)

Co-authored-by: Willow (GHOST) <git@willow.sh>

Author: danielroe

.gitignore

@@ -40,6 +40,7 @@ test-results/
 # generated files
 shared/types/lexicons
 file-tree-sprite.svg
+public/blog/avatar
 
 **/__screenshots__/**
 

app/components/AuthorList.vue

@@ -1,18 +1,16 @@
 <script setup lang="ts">
-import type { Author } from '#shared/schemas/blog'
+import type { ResolvedAuthor } from '#shared/schemas/blog'
 
-const props = defineProps<{
-  authors: Author[]
+defineProps<{
+  authors: ResolvedAuthor[]
   variant?: 'compact' | 'expanded'
 }>()
-
-const { resolvedAuthors } = useBlueskyAuthorProfiles(props.authors)
 </script>
 
 <template>
   <!-- Expanded variant: vertical list with larger avatars -->
   <div v-if="variant === 'expanded'" class="flex flex-wrap items-center gap-4">
-    <div v-for="author in resolvedAuthors" :key="author.name" class="flex items-center gap-2">
+    <div v-for="author in authors" :key="author.name" class="flex items-center gap-2">
       <AuthorAvatar :author="author" size="md" disable-link />
       <div class="flex flex-col">
         <span class="text-sm font-medium text-fg">{{ author.name }}</span>
@@ -34,7 +32,7 @@ const { resolvedAuthors } = useBlueskyAuthorProfiles(props.authors)
   <div v-else class="flex items-center gap-2 min-w-0">
     <div class="flex items-center">
       <AuthorAvatar
-        v-for="(author, index) in resolvedAuthors"
+        v-for="(author, index) in authors"
         :key="author.name"
         :author="author"
         size="md"
@@ -43,7 +41,7 @@ const { resolvedAuthors } = useBlueskyAuthorProfiles(props.authors)
       />
     </div>
     <span class="text-xs text-fg-muted font-mono truncate">
-      {{ resolvedAuthors.map(a => a.name).join(', ') }}
+      {{ authors.map(a => a.name).join(', ') }}
     </span>
   </div>
 </template>

app/components/BlogPostListCard.vue

@@ -1,9 +1,9 @@
 <script setup lang="ts">
-import type { Author } from '#shared/schemas/blog'
+import type { ResolvedAuthor } from '#shared/schemas/blog'
 
 defineProps<{
   /** Authors of the blog post */
-  authors: Author[]
+  authors: ResolvedAuthor[]
   /** Blog Title */
   title: string
   /** Tags such as OpenSource, Architecture, Community, etc. */

app/components/OgImage/BlogPost.vue

@@ -1,10 +1,10 @@
 <script setup lang="ts">
-import type { Author } from '#shared/schemas/blog'
+import type { ResolvedAuthor } from '#shared/schemas/blog'
 
 const props = withDefaults(
   defineProps<{
     title: string
-    authors?: Author[]
+    authors?: ResolvedAuthor[]
     date?: string
     primaryColor?: string
   }>(),
@@ -15,8 +15,6 @@ const props = withDefaults(
   },
 )
 
-const { resolvedAuthors } = useBlueskyAuthorProfiles(props.authors)
-
 const formattedDate = computed(() => {
   if (!props.date) return ''
   try {
@@ -41,17 +39,17 @@ const getInitials = (name: string) =>
     .slice(0, 2)
 
 const visibleAuthors = computed(() => {
-  if (resolvedAuthors.value.length <= 3) return resolvedAuthors.value
-  return resolvedAuthors.value.slice(0, MAX_VISIBLE_AUTHORS)
+  if (props.authors.length <= 3) return props.authors
+  return props.authors.slice(0, MAX_VISIBLE_AUTHORS)
 })
 
 const extraCount = computed(() => {
-  if (resolvedAuthors.value.length <= 3) return 0
-  return resolvedAuthors.value.length - MAX_VISIBLE_AUTHORS
+  if (props.authors.length <= 3) return 0
+  return props.authors.length - MAX_VISIBLE_AUTHORS
 })
 
 const formattedAuthorNames = computed(() => {
-  const allNames = resolvedAuthors.value.map(a => a.name)
+  const allNames = props.authors.map(a => a.name)
   if (allNames.length === 0) return ''
   if (allNames.length === 1) return allNames[0]
   if (allNames.length === 2) return `${allNames[0]} and ${allNames[1]}`
@@ -96,7 +94,7 @@ const formattedAuthorNames = computed(() => {
 
       <!-- Authors -->
       <div
-        v-if="resolvedAuthors.length"
+        v-if="authors.length"
         class="flex items-center gap-4 self-start justify-start flex-nowrap"
         style="font-family: 'Geist', sans-serif"
       >

app/components/global/BlogPostWrapper.vue

@@ -1,11 +1,14 @@
 <script setup lang="ts">
-import type { BlogPostFrontmatter } from '#shared/schemas/blog'
+import type { RawBlogPostFrontmatter } from '#shared/schemas/blog'
 import { generateBlogTID } from '#shared/utils/atproto'
+import { posts } from '#blog/posts'
 
 const props = defineProps<{
-  frontmatter: BlogPostFrontmatter
+  frontmatter: RawBlogPostFrontmatter
 }>()
 
+const post = computed(() => posts.find(p => p.slug === props.frontmatter.slug))
+
 useSeoMeta({
   title: props.frontmatter.title,
   description: props.frontmatter.description || props.frontmatter.excerpt,
@@ -26,7 +29,7 @@ useHead({
 
 defineOgImageComponent('BlogPost', {
   title: props.frontmatter.title,
-  authors: props.frontmatter.authors,
+  authors: post.value?.authors ?? [],
   date: props.frontmatter.date,
 })
 
@@ -50,9 +53,9 @@ const blueskyPostUri = computed(() => blueskyLink.value?.postUri ?? null)
         </span>
       </div>
     </div>
-    <div v-if="frontmatter.authors" class="mb-12 max-w-prose mx-auto">
+    <div v-if="post?.authors" class="mb-12 max-w-prose mx-auto">
       <div class="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4">
-        <AuthorList :authors="frontmatter.authors" variant="expanded" />
+        <AuthorList :authors="post.authors" variant="expanded" />
       </div>
     </div>
     <article class="max-w-prose mx-auto p-2 prose dark:prose-invert">

modules/blog.ts

@@ -5,19 +5,91 @@ import shiki from '@shikijs/markdown-exit'
 import MarkdownItAnchor from 'markdown-it-anchor'
 import { defu } from 'defu'
 import { read } from 'gray-matter'
-import { safeParse } from 'valibot'
-import { BlogPostSchema, type BlogPostFrontmatter } from '../shared/schemas/blog'
+import { array, safeParse } from 'valibot'
+import {
+  AuthorSchema,
+  RawBlogPostSchema,
+  type Author,
+  type BlogPostFrontmatter,
+  type ResolvedAuthor,
+} from '../shared/schemas/blog'
 import { globSync } from 'tinyglobby'
 import { isProduction } from '../config/env'
+import { BLUESKY_API } from '../shared/utils/constants'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import crypto from 'node:crypto'
+
+/**
+ * Fetches Bluesky avatars for a set of authors at build time.
+ * Returns a map of handle → avatar URL.
+ */
+async function fetchBlueskyAvatars(
+  imagesDir: string,
+  handles: string[],
+): Promise<Map<string, string>> {
+  const avatarMap = new Map<string, string>()
+  if (handles.length === 0) return avatarMap
+
+  try {
+    const params = new URLSearchParams()
+    for (const handle of handles) {
+      params.append('actors', handle)
+    }
+
+    const response = await fetch(
+      `${BLUESKY_API}/xrpc/app.bsky.actor.getProfiles?${params.toString()}`,
+    )
+
+    if (!response.ok) {
+      console.warn(`[blog] Failed to fetch Bluesky profiles: ${response.status}`)
+      return avatarMap
+    }
+
+    const data = (await response.json()) as { profiles: Array<{ handle: string; avatar?: string }> }
+
+    for (const profile of data.profiles) {
+      if (profile.avatar) {
+        const hash = crypto.createHash('sha256').update(profile.avatar).digest('hex')
+        const dest = join(imagesDir, `${hash}.jpg`)
+
+        if (!existsSync(dest)) {
+          const res = await fetch(profile.avatar)
+          await writeFile(join(imagesDir, `${hash}.jpg`), res.body!)
+        }
+
+        avatarMap.set(profile.handle, `/blog/avatar/${hash}.jpg`)
+      }
+    }
+  } catch (error) {
+    console.warn(`[blog] Failed to fetch Bluesky avatars:`, error)
+  }
+
+  return avatarMap
+}
+
+/**
+ * Resolves authors with their Bluesky avatars and profile URLs.
+ */
+function resolveAuthors(authors: Author[], avatarMap: Map<string, string>): ResolvedAuthor[] {
+  return authors.map(author => ({
+    ...author,
+    avatar: author.blueskyHandle ? (avatarMap.get(author.blueskyHandle) ?? null) : null,
+    profileUrl: author.blueskyHandle ? `https://bsky.app/profile/${author.blueskyHandle}` : null,
+  }))
+}
 
 /**
  * Scans the blog directory for .md files and extracts validated frontmatter.
  * Returns all posts (including drafts) sorted by date descending.
+ * Resolves Bluesky avatars at build time.
  */
-function loadBlogPosts(blogDir: string): BlogPostFrontmatter[] {
+async function loadBlogPosts(blogDir: string, imagesDir: string): Promise<BlogPostFrontmatter[]> {
   const files: string[] = globSync(join(blogDir, '*.md'))
 
-  const posts: BlogPostFrontmatter[] = []
+  // First pass: extract raw frontmatter and collect all Bluesky handles
+  const rawPosts: Array<{ frontmatter: Record<string, unknown> }> = []
+  const allHandles = new Set<string>()
 
   for (const file of files) {
     const { data: frontmatter } = read(file)
@@ -32,10 +104,33 @@ function loadBlogPosts(blogDir: string): BlogPostFrontmatter[] {
       frontmatter.date = new Date(raw instanceof Date ? raw : String(raw)).toISOString()
     }
 
-    const result = safeParse(BlogPostSchema, frontmatter)
+    // Validate authors before resolving so we can extract handles
+    const authorsResult = safeParse(array(AuthorSchema), frontmatter.authors)
+    if (authorsResult.success) {
+      for (const author of authorsResult.output) {
+        if (author.blueskyHandle) {
+          allHandles.add(author.blueskyHandle)
+        }
+      }
+    }
+
+    rawPosts.push({ frontmatter })
+  }
+
+  // Batch-fetch all Bluesky avatars in a single request
+  const avatarMap = await fetchBlueskyAvatars(imagesDir, [...allHandles])
+
+  // Second pass: validate with raw schema, then enrich authors with avatars
+  const posts: BlogPostFrontmatter[] = []
+
+  for (const { frontmatter } of rawPosts) {
+    const result = safeParse(RawBlogPostSchema, frontmatter)
     if (!result.success) continue
 
-    posts.push(result.output)
+    posts.push({
+      ...result.output,
+      authors: resolveAuthors(result.output.authors, avatarMap),
+    })
   }
 
   // Sort newest first
@@ -47,16 +142,21 @@ export default defineNuxtModule({
   meta: {
     name: 'blog',
   },
-  setup() {
+  async setup() {
     const nuxt = useNuxt()
     const resolver = createResolver(import.meta.url)
     const blogDir = resolver.resolve('../app/pages/blog')
+    const blogImagesDir = resolver.resolve('../public/blog/avatar')
 
     nuxt.options.extensions.push('.md')
     nuxt.options.vite.vue = defu(nuxt.options.vite.vue, {
       include: [/\.vue($|\?)/, /\.(md|markdown)($|\?)/],
     })
 
+    if (!existsSync(blogImagesDir)) {
+      await mkdir(blogImagesDir, { recursive: true })
+    }
+
     addVitePlugin(() =>
       Markdown({
         include: [/\.(md|markdown)($|\?)/],
@@ -76,13 +176,16 @@ export default defineNuxtModule({
       }),
     )
 
+    // Load posts once with resolved Bluesky avatars (shared across template + route rules)
+    const allPosts = await loadBlogPosts(blogDir, blogImagesDir)
+
     // Expose frontmatter for the `/blog` listing page.
     const showDrafts = nuxt.options.dev || !isProduction
     addTemplate({
       filename: 'blog/posts.ts',
       write: true,
       getContents: () => {
-        const posts = loadBlogPosts(blogDir).filter(p => showDrafts || !p.draft)
+        const posts = allPosts.filter(p => showDrafts || !p.draft)
         return [
           `import type { BlogPostFrontmatter } from '#shared/schemas/blog'`,
           ``,
@@ -94,8 +197,7 @@ export default defineNuxtModule({
     nuxt.options.alias['#blog/posts'] = join(nuxt.options.buildDir, 'blog/posts')
 
     // Add X-Robots-Tag header for draft posts to prevent indexing
-    const posts = loadBlogPosts(blogDir)
-    for (const post of posts) {
+    for (const post of allPosts) {
       if (post.draft) {
         nuxt.options.routeRules ||= {}
         nuxt.options.routeRules[`/blog/${post.slug}`] = {