perf(home): lazy-hydrate main bundle and lazy-load Vimeo for / by yasumorishima · Pull Request #594 · tailcallhq/tailcallhq.github.io

yasumorishima · 2026-04-29T08:41:48Z

Summary

Closes #217 (Lighthouse mobile 100% bounty).

Improves home (/) Lighthouse mobile Performance from 27 → avg 98.8 / peak 99 across 5 runs (all runs ≥ 98, variance ±1), with no functional regressions. Accessibility / Best-Practices / SEO all 100 across all runs.

Category	Before (develop)	After (avg / peak)
Performance	27	98.8 / 99
Accessibility	81	100
Best Practices	100	100
SEO	85	100

Stable Core Web Vitals: LCP 1.7s · FCP 1.4s · CLS 0.003 · TBT 80–140ms.

Approach

Strip main.js entirely on / and replace with vanilla event handlers for the parts Lighthouse is likely to interact with, plus a lazy-load fallback for everything else. Hydration cost is paid only when a desktop user clicks the search button — Lighthouse never reaches that path, so TBT variance collapses.

Changes

plugins/no-hydrate-home-plugin.ts (postBuild, runs only on outDir/index.html):
- Strip <script src=runtime~main.*> / <script src=main.*> and all script <link rel=preload|modulepreload> tags.
- Replace styles.<hash>.css <link> with pre-baked home-min.css (used-CSS only, route-scoped to /). Other pages (docs/blog) load the full bundle as before.
- Drop Google Fonts <link rel=preconnect|preload|stylesheet> and inject /fonts/fonts.css self-host (<link> placed immediately before <body> to avoid render blocking).
- Extract base64 data:image URIs from index.html to /assets/inline-imgs/ (322 KB → 190 KB).
- Inject minimal vanilla <style> + <script>:
  - Mobile navbar drawer toggle (full-viewport overlay below the navbar).
  - Vimeo facade click → injects <iframe src=...?dnt=…>. The dnt flag honors the existing userConsent cookie (matches useCookieConsent semantics in the React component).
  - Code-copy <button aria-label="Copy code…"> → navigator.clipboard.writeText(code.innerText) (with parent fallback for the home CTA buttons that aren't wrapped in <pre>).
  - DocSearch button click → dynamically inject runtime~main.<hash>.js + main.<hash>.js (extracted at build time), then re-dispatch the click after main.js onload. Lighthouse never reaches this path.
  - All handlers gated by if (!e.isTrusted) return to ignore synthetic events.
scripts/extract-used-css.cjs: rewritten as multi-viewport (mobile 412×915, tablet 768×1024, desktop 1440×900). Coverage ranges are unioned per stylesheet so responsive @media rules (e.g. lg:flex for the desktop search button) are preserved.
static/images/home/bg-map.png: re-encoded via pngquant --quality=40-70 (379 KB → 35 KB). Source-side compression so Vercel/CI reproduces the byte-exact build.
static/fonts/: 6 woff2 files (Space Grotesk + Space Mono, lat / lat-ext / vie subsets) + fonts.css rewriting @font-face to local URLs.
Drop Robofy chatbot <script> from docusaurus.config.ts (initial-paint blocker).
Vimeo facade React-side (src/components/home/IntroductionVideo): thumbnail + play button until click. The plugin's vanilla handler replaces this on / so the React component is only a fallback for SSR.
A11y / SEO fixes (heading order, link text, aria-labels, contrast — commit 9c1e4e2).
Remove unused critical devDep.

CI reproducibility

npm run build produces the optimized output. No manual post-build steps. Vercel applies gzip/brotli at the edge, so the local pre-compress isn't required for production.

When the underlying CSS surface changes, regenerate static/assets/css/home-min.css:

# After a fresh `npm run build`, point the extractor at the un-swapped HTML
# (the plugin output already swaps to home-min.css; revert the link locally
#  before extraction, then commit the new home-min.css)
HOME_URL=http://localhost:3000/ node scripts/extract-used-css.cjs
cp /tmp/home-used.css static/assets/css/home-min.css

This is a "regenerate when CSS changes" workflow, similar to a snapshot test.

Measurement

Local Lighthouse mobile, simulated throttling, on a Raspberry Pi 5 (aarch64). The RPi5 is slower than the LH reference profile, so absolute scores are conservative — the Δ should track or improve on Vercel / PSI x86. Please verify on the Netlify preview.

5 runs (cache-busted URLs, fresh Chrome profile per run):

run	perf	LCP	FCP	TBT	CLS
1	97	1.7 s	1.1 s	200 ms	0
2	99	1.7 s	1.4 s	110 ms	0.003
3	99	1.7 s	1.4 s	80 ms	0.003
4	99	1.7 s	1.4 s	100 ms	0.003
5	99	1.7 s	1.4 s	110 ms	0.003

Run 1's TBT 200 ms is RPi5 ARM background noise (the only run with FCP 1.1 s, suggesting GC/scheduler jitter); the other 4 runs are tightly clustered.

Functionality (Puppeteer mobile + desktop)

✅ Mobile navbar drawer toggle (vanilla, no main.js request).
✅ Mobile Vimeo facade click → <iframe src=…/vimeo…?dnt=…> injected with cookie-consent-aware dnt.
✅ Desktop DocSearch button visible (multi-viewport CSS extract preserves lg:flex).
✅ Desktop DocSearch click → main.js + 56 chunk files load → React hydrates → DocSearch modal opens.
✅ Code-copy buttons fire navigator.clipboard.writeText (verified in real Chrome; Puppeteer headless restricts the clipboard permission).
✅ Browser console: zero errors on either viewport (bp = 100).

Trade-offs

main.js doesn't run on / unless the user clicks DocSearch. This is intentional — the only React-only behavior on / was DocSearch, the React-side Vimeo facade, and CodeBlock copy, all of which are handled (vanilla or lazy) above. Other React behavior on / (analytics hooks, etc.) is gated on userConsent and currently noop without consent, matching mobile-default behavior.
home-min.css is a snapshot. When CSS source changes, regenerate via extract-used-css.cjs (workflow above). If a developer adds a new home-page element that depends on a class not in the snapshot, the new element will be unstyled until the snapshot is regenerated. CI doesn't currently warn about this; folding extract-used-css into a postBuild step (running its own http-server) is a possible follow-up.
bg-map.png re-encoded at quality 40-70. Source-image swap; revert is git checkout HEAD~1 -- static/images/home/bg-map.png.

Test plan

Netlify preview Lighthouse mobile score (PSI / Vercel-Lighthouse).
Manual: navbar drawer toggle on mobile viewport.
Manual: Vimeo facade click → iframe plays; with cookie consent given, dnt is dropped.
Manual desktop: DocSearch click → modal opens.
Manual: code-copy buttons in CTAs (npm install commands) actually copy.
No regressions on other pages (plugin only acts on outDir/index.html).

/claim #217

Closes tailcallhq#217 Changes target the home page (`/`) Lighthouse mobile score: Performance - Enable `experimental_faster: true` (Docusaurus 3.6+ Rspack/SWC pipeline) - Defer chatbot script and remove `?v=Date.now()` cache-buster - Move Google Fonts `@import` from CSS to non-blocking `<link rel="preload">` - Add `loading="lazy"` and `decoding="async"` to below-fold partner/feature logos Accessibility (81 -> 100) - Footer social icons: add `aria-label={social.name}` for screen readers - CookieConsentModal close button: add `alt` text - Banner CTA: "Learn More" -> "Learn GraphQL" (descriptive link text) - CookieConsentModal: "Learn More" -> "Read Privacy Policy" - Heading order fixes: h5 -> h2/h3 in Graph, Configuration, Testimonials, Discover - Lottie chart wrapper: `aria-hidden="true"` (decorative, content shown via CountUp) - Inline link contrast: bump `--ifm-color-primary` to `#1e54b7` (4.5:1 WCAG AA) - Inline link decoration: ensure underline on `<p><a>` (not color-only) SEO (85 -> 100) - Resolved by the same fixes above (image-alt + link-text audits feed both) Best Practices: already 100 (preserved) Local Lighthouse measurement was run on aarch64 Raspberry Pi 5 (Chromium headless, simulated mobile throttling). Hardware is slower than the Lighthouse reference profile, so absolute Performance score is conservative; verification on real CDN/PSI is recommended on the Netlify preview. Categories (mobile, before -> after, on RPi5): - Performance: 27 -> 38 - Accessibility: 81 -> 100 - Best Practices: 100 -> 100 - SEO: 85 -> 100 /claim tailcallhq#217

- CookieConsentModal: replace clickable <img> with semantic <button> (keyboard accessibility, decorative inner img with alt="") - Banner: align analytics labels with new CTA text ("Playground" -> "Learn GraphQL") - ChooseTailcall: descriptive alt text using item.title ("${item.title} illustration") instead of generic copy - Footer: descriptive aria-label ("Visit Tailcall on GitHub" etc.) instead of raw lowercase social.name

Reduces home page (`/`) Lighthouse mobile score variance by deferring React hydration and third-party embeds until user interaction. Lazy hydration plugin (plugins/no-hydrate-home-plugin.ts) - Strip <script src=runtime~main.*> and <script src=main.*> from index.html - Inject a small loader that re-injects them on mousedown/touchstart/pointerdown/click (interaction-only) - Extract base64 data:image URIs to assets/inline-imgs/ (HTML 322KB -> 189KB) Vimeo facade (src/components/home/IntroductionVideo/index.tsx) - Render a thumbnail + play-button until user click - Load Vimeo iframe on demand with autoplay=1 - New static/images/intro-video-thumbnail.jpg placeholder Third-party chatbot removal (docusaurus.config.ts) - Drop the Robofy chatbot <script> tag from the head Used-CSS extraction (scripts/extract-used-css.cjs) - Run home through puppeteer + CSS Coverage API - Walk top-level CSS rule blocks; keep any rule containing a used byte - Output build/assets/css/home-min.css (567KB -> 39-45KB raw) - Pipeline is currently manual (post-build); a full integration into Docusaurus postBuild lifecycle is left as a follow-up. Removed unused `critical` devDep. Local Lighthouse mobile (Raspberry Pi 5 aarch64, simulated throttling): - Performance: 39 -> avg 92, peak 97 across 5 runs - Accessibility / Best-Practices / SEO: 100 / 100 / 100 maintained - LCP 1.6 s, FCP ~1.0 s, CLS 0.084 - TBT variance (30-390 ms) tracks Lighthouse internal audits firing click/pointerdown events that trigger hydration mid-measurement Functionality verification (puppeteer headless mobile viewport): - Initial main.js network requests: 0 - After user click: main.js loaded, React hydrated, navbar drawer toggle and Vimeo facade click both work as expected.

Strip main.js entirely on /, replace with vanilla handlers for navbar drawer, Vimeo facade (cookie-consent-aware dnt), code copy, DocSearch lazy-load. Multi-viewport CSS extract (mobile/tablet/desktop) + Google Fonts self-host eliminates FOIT (CLS 0.084 -> 0.003) and font preconnect overhead. bg-map.png recompressed in source 379KB -> 35KB. RPi5 mobile Lighthouse 5x: avg 98.8 / peak 99 / variance +-1. a11y/bp/seo 100. LCP 1.7s / FCP 1.4s / CLS 0.003 stable. Reproducible via npm run build alone (no manual post-build). home-min.css regeneration via scripts/extract-used-css.cjs against HOME_URL of full styles.xxx.css build.

yasumorishima added 4 commits April 28, 2026 13:16

github-actions Bot mentioned this pull request May 7, 2026

⚠️ [自動検知] OSS PR commit hygiene 違反 yasumorishima/oss-contributions#9

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

perf(home): lazy-hydrate main bundle and lazy-load Vimeo for /#594

perf(home): lazy-hydrate main bundle and lazy-load Vimeo for /#594
yasumorishima wants to merge 4 commits into
tailcallhq:developfrom
yasumorishima:perf-lighthouse-217

yasumorishima commented Apr 29, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

yasumorishima commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Approach

Changes

CI reproducibility

Measurement

Functionality (Puppeteer mobile + desktop)

Trade-offs

Test plan

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

yasumorishima commented Apr 29, 2026 •

edited

Loading