feat(web): SSR Store SEO Phase 1+2, dynamic metadata, sitemap, warm-cache script; add SSR e2e test + LHCI + docs

brandonkachen · brandonkachen · commit b85728c3b6e4 · 2025-11-04T14:20:35.000-08:00
diff --git a/.github/workflows/lighthouse.yml b/.github/workflows/lighthouse.yml
@@ -0,0 +1,54 @@
+name: Lighthouse CI
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  lhci:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: '1.1.34'
+
+      - name: Install dependencies (workspace)
+        run: bun install --frozen-lockfile
+
+      - name: Build web
+        working-directory: web
+        run: bun run build
+        env:
+          NEXT_PUBLIC_CODEBUFF_APP_URL: http://127.0.0.1:3000
+
+      - name: Start Next server
+        working-directory: web
+        run: |
+          export NEXT_PUBLIC_WEB_PORT=3000
+          export E2E_ENABLE_QUERY_FIXTURE=1
+          nohup bun run start >/tmp/web.log 2>&1 &
+          echo $! > /tmp/web.pid
+          for i in {1..60}; do
+            if curl -sSf http://127.0.0.1:3000/store?e2eFixture=1 >/dev/null; then
+              echo "Server is up"; break; fi; sleep 1; done
+
+      - name: Run Lighthouse CI
+        working-directory: web
+        run: bunx lhci autorun --config=lighthouserc.json
+
+      - name: Upload server logs on failure
+        if: failure()
+        run: |
+          echo "\n--- web server log ---\n"
+          cat /tmp/web.log || true
+
+      - name: Stop Next server
+        if: always()
+        run: |
+          if [ -f /tmp/web.pid ]; then kill $(cat /tmp/web.pid) || true; fi
+
diff --git a/web/README.md b/web/README.md
@@ -76,5 +76,45 @@ The following scripts are available in the `package.json`:
 - `test:watch`: Run unit tests in watch mode
 - `e2e`: Run end-to-end tests
 - `e2e:ui`: Run end-to-end tests with UI
-- `postbuild`: Generate sitemap
+- `postbuild`: Warm Store cache (non-blocking)
+- `warm:store`: Warm Store cache via `/api/agents`
 - `prepare`: Install Husky for managing Git hooks
+
+## SEO & SSR
+
+- Store SSR: `src/app/store/page.tsx` renders agents server-side using cached data (ISR `revalidate=600`).
+- Client fallback: `src/app/store/store-client.tsx` only fetches `/api/agents` if SSR data is empty.
+- Dynamic metadata:
+  - Store: `src/app/store/page.tsx`
+  - Publisher: `src/app/publishers/[id]/page.tsx`
+  - Agent detail: `src/app/publishers/[id]/agents/[agentId]/[version]/page.tsx`
+
+### Warm the Store cache
+
+- Script: `scripts/warm-store-cache.ts`
+- Local: `bun run -C web warm:store`
+- CI/CD: run after deploy; set `NEXT_PUBLIC_CODEBUFF_APP_URL` to your deployed base URL.
+
+### E2E tests for SSR and hydration
+
+- Hydration fallback: `src/__tests__/e2e/store-hydration.spec.ts`
+- SSR HTML: `src/__tests__/e2e/store-ssr.spec.ts` (JavaScript disabled) using server-side fixture `src/app/store/e2e-fixture.ts` when `E2E_ENABLE_QUERY_FIXTURE=1`.
+
+Run locally:
+
+```
+cd web
+bun run e2e
+```
+
+## Lighthouse CI
+
+- Config: `lighthouserc.json`
+- Workflow: `.github/workflows/lighthouse.yml`
+
+Run locally:
+
+```
+cd web
+bunx lhci autorun --config=lighthouserc.json
+```
diff --git a/web/lighthouserc.json b/web/lighthouserc.json
@@ -0,0 +1,25 @@
+{
+  "ci": {
+    "collect": {
+      "url": [
+        "http://127.0.0.1:3000/store?e2eFixture=1"
+      ],
+      "numberOfRuns": 1,
+      "settings": {
+        "preset": "desktop"
+      }
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["warn", { "minScore": 0.8 }],
+        "categories:seo": ["warn", { "minScore": 0.9 }],
+        "categories:accessibility": ["warn", { "minScore": 0.9 }],
+        "categories:best-practices": ["warn", { "minScore": 0.9 }]
+      }
+    },
+    "upload": {
+      "target": "temporary-public-storage"
+    }
+  }
+}
+
diff --git a/web/package.json b/web/package.json
@@ -14,6 +14,7 @@
     "build": "next build 2>&1 | sed '/Contentlayer esbuild warnings:/,/^]/d'",
     "start": "next start",
     "preview": "bun run build && bun run start",
+    "postbuild": "bun run warm:store || true",
     "contentlayer": "contentlayer build",
     "lint": "next lint",
     "lint:fix": "next lint --fix",
@@ -24,6 +25,7 @@
     "test:watch": "jest --watchAll",
     "e2e": "playwright test",
     "e2e:ui": "playwright test --ui",
+    "warm:store": "bun run scripts/warm-store-cache.ts",
     "discord:start": "bun run scripts/discord/index.ts",
     "discord:register": "bun run scripts/discord/register-commands.ts",
     "clean": "rm -rf .next"
@@ -132,6 +134,7 @@
     "typescript": "^5",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
-    "vfile-matter": "^5.0.1"
+    "vfile-matter": "^5.0.1",
+    "@lhci/cli": "^0.13.0"
   }
 }
diff --git a/web/playwright.config.ts b/web/playwright.config.ts
@@ -31,5 +31,8 @@ export default defineConfig({
     command: 'NEXT_PUBLIC_WEB_PORT=3001 bun run dev',
     url: 'http://127.0.0.1:3001',
     reuseExistingServer: !process.env.CI,
+    env: {
+      E2E_ENABLE_QUERY_FIXTURE: '1',
+    },
   },
 })
diff --git a/web/scripts/warm-store-cache.ts b/web/scripts/warm-store-cache.ts
@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+import 'dotenv/config'
+
+const base = process.env.NEXT_PUBLIC_CODEBUFF_APP_URL || 'http://localhost:3000'
+const url = `${base}/api/agents`
+
+async function main() {
+  try {
+    const res = await fetch(url, {
+      headers: {
+        'User-Agent': 'Codebuff-Warm-Store-Cache',
+        Accept: 'application/json',
+      },
+    })
+    if (!res.ok) {
+      console.error(`Warm cache failed: ${res.status} ${res.statusText}`)
+      process.exitCode = 0 // do not fail pipeline
+      return
+    }
+
+    const data = (await res.json()) as unknown[]
+    console.log(
+      `Warm cache succeeded: fetched ${Array.isArray(data) ? data.length : 0} agents from ${url}`,
+    )
+  } catch (err) {
+    console.error(`Warm cache error: ${(err as Error).message}`)
+    // Do not fail build/postbuild step
+    process.exitCode = 0
+  }
+}
+
+await main()
+
diff --git a/web/src/__tests__/e2e/store-ssr.spec.ts b/web/src/__tests__/e2e/store-ssr.spec.ts
@@ -0,0 +1,16 @@
+import { test, expect } from '@playwright/test'
+
+// Disable JS to validate pure SSR HTML
+test.use({ javaScriptEnabled: false })
+
+test('SSR HTML contains at least one agent card', async ({ page }) => {
+  const response = await page.goto('/store?e2eFixture=1', {
+    waitUntil: 'domcontentloaded',
+  })
+  expect(response).not.toBeNull()
+  const html = await response!.text()
+
+  // Validate SSR output contains agent content (publisher + id)
+  expect(html).toContain('@codebuff')
+  expect(html).toContain('>base<')
+})
diff --git a/web/src/app/publishers/[id]/agents/[agentId]/[version]/page.tsx b/web/src/app/publishers/[id]/agents/[agentId]/[version]/page.tsx
@@ -58,12 +58,27 @@ export async function generateMetadata({ params }: AgentDetailPageProps) {
       ? JSON.parse(agent[0].data)
       : agent[0].data
   const agentName = agentData.name || params.agentId
+  // Fetch publisher for OG image
+  const pub = await db
+    .select()
+    .from(schema.publisher)
+    .where(eq(schema.publisher.id, params.id))
+    .limit(1)
+
+  const title = `${agentName} v${agent[0].version} - Agent Details`
+  const description =
+    agentData.description || `View details for ${agentName} version ${agent[0].version}`
+  const ogImages = (pub?.[0]?.avatar_url ? [pub[0].avatar_url] : []) as string[]
 
   return {
-    title: `${agentName} v${agent[0].version} - Agent Details`,
-    description:
-      agentData.description ||
-      `View details for ${agentName} version ${agent[0].version}`,
+    title,
+    description,
+    openGraph: {
+      title,
+      description,
+      type: 'article',
+      images: ogImages,
+    },
   }
 }
 
diff --git a/web/src/app/publishers/[id]/page.tsx b/web/src/app/publishers/[id]/page.tsx
@@ -29,11 +29,20 @@ export async function generateMetadata({ params }: PublisherPageProps) {
     }
   }
 
+  const title = `${publisher[0].name} - Codebuff Publisher`
+  const description =
+    publisher[0].bio || `View ${publisher[0].name}'s published agents on Codebuff`
+  const ogImages = (publisher[0].avatar_url ? [publisher[0].avatar_url] : []) as string[]
+
   return {
-    title: `${publisher[0].name} - Codebuff Publisher`,
-    description:
-      publisher[0].bio ||
-      `View ${publisher[0].name}'s published agents on Codebuff`,
+    title,
+    description,
+    openGraph: {
+      title,
+      description,
+      type: 'profile',
+      images: ogImages,
+    },
   }
 }
 
diff --git a/web/src/app/sitemap.ts b/web/src/app/sitemap.ts
@@ -1,19 +1,61 @@
 import { env } from '@codebuff/common/env'
+import { getCachedAgents } from '@/server/agents-data'
 
 import type { MetadataRoute } from 'next'
 
-export default function sitemap(): MetadataRoute.Sitemap {
-  return [
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const base = env.NEXT_PUBLIC_CODEBUFF_APP_URL || 'http://localhost:3000'
+  const toUrl = (path: string) => `${base}${path}`
+
+  const items: MetadataRoute.Sitemap = [
     {
-      url: env.NEXT_PUBLIC_CODEBUFF_APP_URL || '/',
+      url: toUrl('/'),
       lastModified: new Date(),
       changeFrequency: 'yearly',
       priority: 1,
       alternates: {
         languages: {
-          pl: `${env.NEXT_PUBLIC_CODEBUFF_APP_URL}/pl`,
+          pl: toUrl('/pl'),
         },
       },
     },
+    {
+      url: toUrl('/store'),
+      lastModified: new Date(),
+      changeFrequency: 'hourly',
+      priority: 0.9,
+    },
   ]
+
+  // Include agent detail pages and publisher pages derived from cached store data
+  try {
+    const agents = await getCachedAgents()
+
+    const seenPublishers = new Set<string>()
+    for (const agent of agents) {
+      const pubId = agent.publisher?.id
+      if (pubId && !seenPublishers.has(pubId)) {
+        items.push({
+          url: toUrl(`/publishers/${pubId}`),
+          lastModified: new Date(agent.last_used || agent.created_at),
+          changeFrequency: 'daily',
+          priority: 0.7,
+        })
+        seenPublishers.add(pubId)
+      }
+
+      if (pubId && agent.id && agent.version) {
+        items.push({
+          url: toUrl(`/publishers/${pubId}/agents/${agent.id}/${agent.version}`),
+          lastModified: new Date(agent.last_used || agent.created_at),
+          changeFrequency: 'daily',
+          priority: 0.8,
+        })
+      }
+    }
+  } catch {
+    // If fetching fails, fall back to base entries only
+  }
+
+  return items
 }
diff --git a/web/src/app/store/agents-data.ts b/web/src/app/store/agents-data.ts
diff --git a/web/src/app/store/e2e-fixture.ts b/web/src/app/store/e2e-fixture.ts
diff --git a/web/src/app/store/page.tsx b/web/src/app/store/page.tsx
diff --git a/web/src/server/agents-data.ts b/web/src/server/agents-data.ts

Original file line number	Diff line number	Diff line change
`@@ -29,11 +29,20 @@ export async function generateMetadata({ params }: PublisherPageProps) {`
`29`	`29`	`}`
`30`	`30`	`}`
`31`	`31`
	`32`	+ const title = `${publisher[0].name} - Codebuff Publisher`
	`33`	`+ const description =`
	`34`	+ publisher[0].bio \|\| `View ${publisher[0].name}'s published agents on Codebuff`
	`35`	`+ const ogImages = (publisher[0].avatar_url ? [publisher[0].avatar_url] : []) as string[]`
	`36`	`+`
`32`	`37`	`return {`
`33`		- title: `${publisher[0].name} - Codebuff Publisher`,
`34`		`- description:`
`35`		`- publisher[0].bio \|\|`
`36`		- `View ${publisher[0].name}'s published agents on Codebuff`,
	`38`	`+ title,`
	`39`	`+ description,`
	`40`	`+ openGraph: {`
	`41`	`+ title,`
	`42`	`+ description,`
	`43`	`+ type: 'profile',`
	`44`	`+ images: ogImages,`
	`45`	`+ },`
`37`	`46`	`}`
`38`	`47`	`}`
`39`	`48`