From 6406eb4cc63cedd7f948a53c765dbc5cdf2af352 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 16 May 2026 14:45:56 +0000 Subject: [PATCH 1/6] chore: add lighthouse perf/best-practices skills and reviewer agent Adds repo-tailored .claude tooling derived from the mobile/desktop Lighthouse reports for onelitefeather.net/de: skills for performance (TBT, CLS, third-party scripts, render-blocking) and best-practices (console errors, third-party cookies, bf-cache, source maps), plus an independent lighthouse-performance-reviewer subagent. Documented in AGENTS.md as the single source of truth. https://claude.ai/code/session_01KoQywVk4Mj9EqgxScc4Yrr --- .../agents/lighthouse-performance-reviewer.md | 51 ++++++++++++ .../skills/lighthouse-best-practices/SKILL.md | 70 ++++++++++++++++ .claude/skills/lighthouse-perf/SKILL.md | 79 +++++++++++++++++++ AGENTS.md | 13 +++ 4 files changed, 213 insertions(+) create mode 100644 .claude/agents/lighthouse-performance-reviewer.md create mode 100644 .claude/skills/lighthouse-best-practices/SKILL.md create mode 100644 .claude/skills/lighthouse-perf/SKILL.md diff --git a/.claude/agents/lighthouse-performance-reviewer.md b/.claude/agents/lighthouse-performance-reviewer.md new file mode 100644 index 0000000..23dac5a --- /dev/null +++ b/.claude/agents/lighthouse-performance-reviewer.md @@ -0,0 +1,51 @@ +--- +name: lighthouse-performance-reviewer +description: >- + Use to independently review changes for Lighthouse performance and + best-practices regressions before a PR is opened, when adding/altering + third-party scripts, analytics, cookies, images, or SSR/hydration + behaviour, or when a Lighthouse score drops. Reports findings only; does + not edit code unless explicitly asked. +tools: Read, Grep, Glob, Bash +model: sonnet +--- + +You are a web-performance specialist reviewing changes to a Nuxt 4 / Vue 3 +site (Tailwind v4, @nuxt/content, @nuxtjs/i18n, @nuxt/image Cloudflare +provider) deployed on Cloudflare Workers, with `nuxt-posthog`, +`nuxt-gtag`, and `nuxt-vitalizer` installed. + +Context you must keep in mind: +- CI Lighthouse (`.lighthouserc.json`) runs the **desktop** preset only. + The real problem is **mobile**: TBT ~1.5 s, CLS ~0.28, TTI ~7.5 s + (desktop performance is ~0.93). Always reason about mobile. +- Best-practices is ~0.73 and gated only as `warn` — treat it as a + hard requirement not to regress. + +Process: +1. Determine changed files: `git diff --name-only main...HEAD`, focusing on + `pages/`, `components/`, `layouts/`, `plugins/`, `composables/`, + `nuxt.config.ts`, `package.json`, and `assets/css/`. +2. Read each changed file fully and apply the `lighthouse-perf` and + `lighthouse-best-practices` skill checklists. +3. Specifically flag: new/eager third-party scripts, analytics or cookies + set before consent, blocking CSS/JS added to `nuxt.config.ts`, + client-only LCP content, layout-shift risks (unsized media/embeds, + late-inserted content — the footer is a known CLS culprit), large or + un-split bundles, SSR/hydration mismatches, and missing source maps. +4. If a build is feasible, run `pnpm build`; otherwise reason statically + about bundle/runtime impact. + +Output a single report grouped by severity: +- **Blocker** — eager third-party script on the critical path, new + pre-consent cookie, hydration mismatch, render-blocking asset added, + client-only LCP, unsized late content causing CLS. +- **Should fix** — unsplit interaction-only JS, missing deferral/idle + loading, missing image dimensions, missing source maps. +- **Nice to have** — minor polish and payload trims. + +Each finding: `file:line`, the problem, its likely metric impact (TBT / +LCP / CLS / best-practices), and a concrete Nuxt-idiomatic fix. Where a +runtime claim matters, state that a mobile Lighthouse pass is needed to +confirm. Be precise and brief. Do not modify files unless the caller +explicitly instructs you to. diff --git a/.claude/skills/lighthouse-best-practices/SKILL.md b/.claude/skills/lighthouse-best-practices/SKILL.md new file mode 100644 index 0000000..735b4ff --- /dev/null +++ b/.claude/skills/lighthouse-best-practices/SKILL.md @@ -0,0 +1,70 @@ +--- +name: lighthouse-best-practices +description: >- + Diagnose and fix Lighthouse "Best Practices" failures on this Nuxt 4 site + (console errors, hydration mismatches, third-party cookies, back/forward + cache, missing source maps). Use when changing scripts, analytics, cookies, + SSR/hydration behaviour, or when the best-practices score is below 0.9. +--- + +# Lighthouse Best Practices Review (Nuxt 4 / Cloudflare) + +Current best-practices score is ~0.73 (CI gate is `warn`, minScore 0.9 — +keep it green, do not let it regress further). The failing audits and the +fix patterns for this repo: + +## Console errors (`errors-in-console`) + +Two known errors: + +- **`net::ERR_CERT_AUTHORITY_INVALID`** — a resource is loaded over a + host with an invalid/untrusted certificate. Find the offending request + (analytics proxy, image/CDN host, embed) and serve it from a valid-cert + origin or the first-party proxy. Never ship mixed/invalid-cert requests. +- **`Hydration completed but contains mismatches`** — SSR markup differs + from client render. Common causes here: `Date`/locale/random values + rendered without ``, `import.meta.client` branching in + templates, i18n/`useState` not seeded on the server, or + browser-only APIs read during setup. Fix the markup-divergence at the + source; do not silence it. Zero console errors/warnings is the bar. + +## Third-party cookies (`third-party-cookies`) + +`NID` (Google) and PostHog cookies are set unconditionally. Fixes: + +- Gate `nuxt-gtag` and `nuxt-posthog` initialisation behind explicit + cookie consent; do not set analytics cookies before opt-in. +- Prefer first-party proxying (PostHog `proxy: true` is already set — + keep analytics requests same-origin) and cookieless/consentless modes + where the vendor supports them. +- This audit overlaps with the `lighthouse-perf` deferral work — deferring + + consent-gating analytics fixes both at once. + +## Back/forward cache (`bf-cache`) + +"Navigation was cancelled before the page could be restored." Avoid +`unload` listeners, keep `Cache-Control: no-store` off HTML responses, and +do not hold open connections that block bfcache. Verify in Chrome DevTools +→ Application → Back/forward cache → "Test". + +## Missing source maps (`valid-source-maps`) + +Large first-party JS ships without source maps. Enable production client +source maps in `nuxt.config.ts` (e.g. `sourcemap.client`) so the audit +passes and prod stack traces are usable. Confirm the build still deploys +on the Cloudflare `cloudflare_module` preset. + +## Inspector / cookie issues (`inspector-issues`) + +Resolve the Chrome "Issues" panel entries (cookie attribute / deprecation +warnings) surfaced by the same analytics scripts — usually fixed by the +consent gating and first-party proxying above. + +## Verification (required) + +1. `pnpm build` must pass. +2. `pnpm seo:lighthouse`; report the `best-practices` score and confirm + no audit listed above regressed. +3. Manually confirm a clean console (no errors/warnings) and a passing + bfcache test in DevTools for any change touching scripts, cookies, + SSR, or hydration. diff --git a/.claude/skills/lighthouse-perf/SKILL.md b/.claude/skills/lighthouse-perf/SKILL.md new file mode 100644 index 0000000..1e516c4 --- /dev/null +++ b/.claude/skills/lighthouse-perf/SKILL.md @@ -0,0 +1,79 @@ +--- +name: lighthouse-perf +description: >- + Diagnose and fix Lighthouse performance regressions on this Nuxt 4 site + (TBT, LCP, CLS, JS execution, third-party scripts, render-blocking). Use + whenever a page change can affect load/runtime cost, when adding scripts or + modules, or when the Lighthouse performance score drops — especially on the + mobile form factor, which CI does not yet cover. +--- + +# Lighthouse Performance Review (Nuxt 4 / Cloudflare) + +CI (`.lighthouserc.json`) only runs the **desktop** preset. The known +problem profile is **mobile**: TBT ~1.5 s, CLS ~0.28, TTI ~7.5 s while +desktop is ~0.93. Always re-check mobile after changes — desktop green +does not mean mobile is fine. + +Apply this checklist to changed `.vue`/`.ts` files under `pages/`, +`components/`, `layouts/`, `plugins/`, and to `nuxt.config.ts`. + +## Third-party scripts (biggest TBT lever) + +The main-thread cost is dominated by PostHog (`nuxt-posthog`, including +`surveys.js` / `posthog-recorder.js`) and Google Ads/gtag +(`nuxt-gtag`, `gtag/js?id=AW-...`). + +- `nuxt-vitalizer` is installed and enabled but **unconfigured**. Configure + it (`disableStylesheets`/`prefetchLinks` and especially delayed/idle + hydration) before hand-rolling anything. +- Defer non-critical third-party JS until idle or first interaction — never + load analytics/session-recording during initial render. Use + `useScriptEventPage`/Nuxt Scripts patterns, `requestIdleCallback`, or the + module's lazy/consent gate. PostHog session recording and surveys must + load **after** the page is interactive. +- Consider PartyTown / web-worker offload for gtag if it cannot be deferred. +- Gate analytics behind cookie consent — this also fixes the + best-practices cookie audit (see `lighthouse-best-practices` skill). +- Never add a new third-party `