From 12407d473d9b9782a8686f5bfcf59ea5931022d6 Mon Sep 17 00:00:00 2001 From: Amruth Pillai Date: Tue, 28 Jul 2026 07:36:27 +0200 Subject: [PATCH] docs: plan SEO and AEO performance improvements --- .../plans/2026-07-28-seo-aeo-performance.md | 697 ++++++++++++++++++ 1 file changed, 697 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-28-seo-aeo-performance.md diff --git a/docs/superpowers/plans/2026-07-28-seo-aeo-performance.md b/docs/superpowers/plans/2026-07-28-seo-aeo-performance.md new file mode 100644 index 000000000..edd56275b --- /dev/null +++ b/docs/superpowers/plans/2026-07-28-seo-aeo-performance.md @@ -0,0 +1,697 @@ +# SEO/AEO Performance Improvements Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Improve the homepage bootstrap, LCP media path, initial root metadata, media caching, and canonical documentation URLs without adding SSR or new dependencies. + +**Architecture:** Keep each change in its current owner: the server web fallback injects root-only SEO and cache headers, the homepage hero uses native lazy video behavior, the static HTML protects the module bootstrap, and Mintlify config owns documentation redirects. Existing client-rendered SEO remains as the hydration and client-navigation fallback. + +**Tech Stack:** TypeScript, React 19, TanStack Router, Hono, Vitest, Testing Library, Vite, Mintlify, ffmpeg, cwebp. + +## Global Constraints + +- Do not add a dependency, package, SSR layer, prerenderer, special AEO schema, or `llms.txt` work. +- Preserve existing `noindex, follow` behavior for application shells and public resume routes. +- Do not add unconfirmed LinkedIn, AI-provider, v4, or placeholder redirects. +- Keep the existing WebSite, SoftwareApplication/WebApplication, Project, and FAQPage JSON-LD facts. +- Keep `/videos/` limited to versioned immutable media filenames. +- Do not claim field LCP, Core Web Vitals, or GSC validation from local verification. +- Do not use the write-capable repository-wide `pnpm check`; run focused non-mutating checks. + +--- + +### Task 1: Initial root metadata and versioned-media caching + +**Files:** + +- Modify: `apps/server/src/static/web.test.ts` +- Modify: `apps/server/src/static/web.ts` + +**Interfaces:** + +- Consumes: `Request.url`, the built `apps/web/dist/index.html`, and Hono `serveStatic.onFound`. +- Produces: the unchanged `handleWebApp(request: Request): Promise` interface and the unchanged `serveWebDistStatic` middleware export. + +- [ ] **Step 1: Make the static middleware options observable in the existing test** + +Replace the current `serveStatic` mock with a hoisted mock and capture its options immediately after importing `web.ts`: + +```ts +const mocks = vi.hoisted(() => ({ + serveStatic: vi.fn((_options?: unknown) => vi.fn()), +})); + +vi.mock("@hono/node-server/serve-static", () => ({ + serveStatic: mocks.serveStatic, +})); + +type StaticOptions = { + onFound?: ( + path: string, + context: { + req: { path: string }; + header: (name: string, value: string) => void; + }, + ) => void | Promise; +}; + +const { handleWebApp } = await import("./web"); +const staticOptions = mocks.serveStatic.mock.calls[0]?.[0] as StaticOptions | undefined; +``` + +- [ ] **Step 2: Write the failing root metadata test** + +Add this test to `apps/server/src/static/web.test.ts`: + +```ts +it("injects canonical metadata and structured data into tracking-parameter root requests only", async () => { + vi.mocked(fs.readFile).mockResolvedValue(` + + + + Reactive Resume — A free and open-source resume builder + + +
+ + `); + + const response = await handleWebApp(new Request("https://example.com/?utm_source=search")); + const html = await response.text(); + + expect(html).toContain(''); + expect(html).toContain(''); + expect(html).toContain(''); + expect(html).toContain(''); + expect(html).toContain('id="reactive-resume-structured-data"'); + expect(html).toContain('"@type":["SoftwareApplication","WebApplication"]'); + expect(html).not.toContain("utm_source"); + + const dashboardResponse = await handleWebApp(new Request("https://example.com/dashboard")); + expect(await dashboardResponse.text()).not.toContain('rel="canonical"'); +}); +``` + +- [ ] **Step 3: Write the failing immutable-cache test** + +Add this test beside the root metadata test: + +```ts +it("caches versioned homepage media immutably", async () => { + const headers = new Headers(); + + await staticOptions?.onFound?.("", { + req: { path: "/videos/timelapse-v1.mp4" }, + header: (name, value) => headers.set(name, value), + }); + + expect(headers.get("Cache-Control")).toBe("public, max-age=31536000, immutable"); +}); +``` + +- [ ] **Step 4: Run the focused server test and verify RED** + +Run: + +```bash +pnpm --filter server test -- src/static/web.test.ts +``` + +Expected: two failures. The root response lacks canonical/JSON-LD markup and the static middleware has no `onFound` callback. + +- [ ] **Step 5: Add root metadata constants and serializer** + +Add the following block after `BASE_SECURITY_HEADERS` in `apps/server/src/static/web.ts`: + +```ts +const ROOT_TITLE = "Reactive Resume — A free and open-source resume builder"; +const ROOT_DESCRIPTION = + "Reactive Resume is a free and open-source resume builder that simplifies the process of creating, updating, and sharing your resume."; +const ROOT_POSTER_PATH = "/videos/timelapse-v1.webp"; +const ROOT_FAQ_ITEMS = [ + { + question: "Is Reactive Resume really free?", + answer: + "Yes! Reactive Resume is completely free to use, with no hidden costs, premium tiers, or subscription fees. It's open-source and will always remain free.", + }, + { + question: "How is my data protected?", + answer: + "Your data is stored securely and is never shared with third parties. You can also self-host Reactive Resume on your own servers for complete control over your data.", + }, + { + question: "Can I export my resume to PDF?", + answer: + "Absolutely! You can export your resume to PDF with a single click. The exported PDF maintains all your formatting and styling perfectly.", + }, + { + question: "Is Reactive Resume available in multiple languages?", + answer: + "Yes, Reactive Resume is available in multiple languages. You can choose your preferred language in the settings page, or using the language switcher in the top right corner. If you don't see your language, or you would like to improve the existing translations, you can contribute to the translations on Crowdin.", + }, + { + question: "What makes Reactive Resume different from other resume builders?", + answer: + "Reactive Resume is open-source, privacy-focused, and completely free. Unlike other resume builders, it doesn't show ads, track your data, or limit your features behind a paywall.", + }, + { + question: "How do I share my resume?", + answer: + "You can share your resume via a unique public URL, protect it with a password, or download it as a PDF to share directly. The choice is yours!", + }, +] as const; + +function createRootSeoMarkup(canonicalUrl: string) { + const origin = new URL(canonicalUrl).origin; + const imageUrl = `${origin}/opengraph/banner.jpg`; + const structuredData = { + "@context": "https://schema.org", + "@graph": [ + { + "@type": "WebSite", + name: "Reactive Resume", + url: canonicalUrl, + }, + { + "@type": ["SoftwareApplication", "WebApplication"], + name: "Reactive Resume", + url: canonicalUrl, + description: ROOT_DESCRIPTION, + applicationCategory: "BusinessApplication", + operatingSystem: "Web", + isAccessibleForFree: true, + offers: { + "@type": "Offer", + price: "0", + priceCurrency: "USD", + }, + codeRepository: "https://github.com/amruthpillai/reactive-resume", + }, + { + "@type": "Project", + name: "Reactive Resume", + url: canonicalUrl, + sameAs: ["https://github.com/amruthpillai/reactive-resume"], + }, + { + "@type": "FAQPage", + mainEntity: ROOT_FAQ_ITEMS.map((item) => ({ + "@type": "Question", + name: item.question, + acceptedAnswer: { + "@type": "Answer", + text: item.answer, + }, + })), + }, + ], + }; + + return ` + + + + + + + + + + + + + + `; +} +``` + +- [ ] **Step 6: Add the immutable media header** + +Replace the current `serveWebDistStatic` declaration with: + +```ts +export const serveWebDistStatic = serveStatic({ + root: staticRoot, + onFound: (_path, context) => { + if (context.req.path.startsWith("/videos/")) { + context.header("Cache-Control", "public, max-age=31536000, immutable"); + } + }, +}); +``` + +- [ ] **Step 7: Inject metadata only for the root pathname** + +Parse the request URL once and replace the closing head only for `/`: + +```ts +export async function handleWebApp(request: Request) { + const isHead = request.method === "HEAD"; + const requestUrl = new URL(request.url); + const pathname = requestUrl.pathname; + + if (!isNoindexShellPath(pathname) && isAssetPath(pathname)) { + return new Response(isHead ? null : "Not Found", { status: 404 }); + } + + const headers = getFallbackResponseHeaders(pathname); + if (!headers) return notFoundResponse({ head: isHead, noindex: true }); + + if (isHead) return new Response(null, { status: 200, headers }); + + const html = await fs.readFile(indexHtmlPath, "utf-8"); + const canonicalUrl = new URL("/", requestUrl.origin).toString(); + const responseHtml = pathname === "/" ? html.replace("", `${createRootSeoMarkup(canonicalUrl)}`) : html; + + return new Response(responseHtml, { headers }); +} +``` + +- [ ] **Step 8: Run the focused server test and verify GREEN** + +Run: + +```bash +pnpm --filter server test -- src/static/web.test.ts +``` + +Expected: all tests in `src/static/web.test.ts` pass. + +- [ ] **Step 9: Run the focused server typecheck** + +Run: + +```bash +pnpm --filter server typecheck +``` + +Expected: exit code 0. + +- [ ] **Step 10: Commit Task 1** + +```bash +git add apps/server/src/static/web.test.ts apps/server/src/static/web.ts +git commit -m "fix(server): emit initial homepage SEO metadata" +``` + +--- + +### Task 2: Homepage poster, interaction-loaded video, and Rocket Loader exclusion + +**Files:** + +- Create: `apps/web/src/routes/_home/-sections/hero.test.tsx` +- Modify: `apps/web/src/routes/_home/-sections/hero.tsx` +- Modify: `apps/web/src/routes/_home/index.tsx` +- Modify: `apps/web/index.html` +- Rename: `apps/web/public/videos/timelapse.mp4` to `apps/web/public/videos/timelapse-v1.mp4` +- Create: `apps/web/public/videos/timelapse-v1.webp` + +**Interfaces:** + +- Consumes: the existing `Hero` component and TanStack route head descriptor. +- Produces: the unchanged `Hero(): JSX.Element` interface and versioned `/videos/timelapse-v1.{webp,mp4}` public media URLs. + +- [ ] **Step 1: Write the failing hero media test** + +Create `apps/web/src/routes/_home/-sections/hero.test.tsx`: + +```tsx +// @vitest-environment happy-dom + +import type { PropsWithChildren } from "react"; +import { i18n } from "@lingui/core"; +import { I18nProvider } from "@lingui/react"; +import { render } from "@testing-library/react"; +import { describe, expect, it, vi } from "vitest"; + +type LinkProps = PropsWithChildren<{ + to: string; +}>; + +vi.mock("@tanstack/react-router", () => ({ + Link: ({ children, to, ...rest }: LinkProps) => ( + + {children} + + ), +})); + +vi.mock("@/components/animation/comet-card", () => ({ + CometCard: ({ children }: PropsWithChildren) =>
{children}
, +})); + +vi.mock("@/components/animation/spotlight", () => ({ + Spotlight: () =>
, +})); + +i18n.loadAndActivate({ locale: "en", messages: {} }); + +const { Hero } = await import("./hero"); + +describe("Hero", () => { + it("shows a poster and waits for user interaction before loading the video", () => { + const { container } = render( + + + , + ); + const video = container.querySelector("video"); + + expect(video).toHaveAttribute("poster", "/videos/timelapse-v1.webp"); + expect(video).toHaveAttribute("preload", "none"); + expect(video).toHaveAttribute("src", "/videos/timelapse-v1.mp4"); + expect(video).toHaveAttribute("controls"); + expect(video).not.toHaveAttribute("autoplay"); + }); +}); +``` + +- [ ] **Step 2: Run the hero test and verify RED** + +Run: + +```bash +pnpm --filter web test -- src/routes/_home/-sections/hero.test.tsx +``` + +Expected: failure because the existing video autoplays and has no poster, controls, or `preload="none"`. + +- [ ] **Step 3: Version the video and generate the poster** + +Run: + +```bash +git mv apps/web/public/videos/timelapse.mp4 apps/web/public/videos/timelapse-v1.mp4 +poster_tmp_dir=$(mktemp -d /tmp/reactive-resume-poster.XXXXXX) +ffmpeg -loglevel error -ss 00:00:03 -i apps/web/public/videos/timelapse-v1.mp4 -frames:v 1 "$poster_tmp_dir/frame.png" +cwebp -quiet -q 82 "$poster_tmp_dir/frame.png" -o apps/web/public/videos/timelapse-v1.webp +magick identify -format '%wx%h %b\n' apps/web/public/videos/timelapse-v1.webp +``` + +Expected: `1146x720` and a WebP size substantially below the 4.2 MB video. + +- [ ] **Step 4: Replace autoplay with native lazy video behavior** + +Replace the video element in `apps/web/src/routes/_home/-sections/hero.tsx` with: + +```tsx +