Skip to content

perf: inline critical assets, cache the home page, and slim the Worker bundle - #16

Merged
phatpham9 merged 3 commits into
mainfrom
perf/first-load-caching-deps
Nov 13, 2026
Merged

phatpham9 merged 3 commits into
mainfrom
perf/first-load-caching-deps

Conversation

@phatpham9

@phatpham9 phatpham9 commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary

First load / rendering

  • Inline style.css and the pre-paint theme bootstrap into the server-rendered HTML. Both are read once per isolate through the ASSETS binding, so the files stay the single source of truth.
  • Edge-cache GET / per URL for five minutes via the Cache API, keyed by APP_VERSION so every deploy invalidates it. Local wrangler dev (APP_VERSION=dev) skips this cache so template/CSS edits are visible immediately.
  • Reduce home rendering from five sequential D1 reads to two parallel reads; skip the per-source dashboard() query used only for error banners. Parallelize dashboard()/healthPayload() queries.
  • Add web-static/_headers with one-year immutable caching for versioned static assets. service-worker.js stays revalidated.
  • Remove the startup forced reflow in preview action placement; sync heights only when the panel is visible.
  • Deduplicate favicon requests and add a buildErrors contract test.

Dependency upgrades

Package Before After
@cloudflare/workers-types 4.20260621.1 5.20261113.1
typescript 5.9.3 7.0.2
vitest 3.2.6 5.1.0
wrangler 4.103.0 4.161.0
linkedom 0.18.12 removed
node-html-parser — 9.0.7

npm audit drops from 12 vulnerabilities (2 critical, 8 high, 1 moderate, 1 low) to 0. npm outdated is empty.

Parser replacement

  • core/sources/dom.ts now wraps node-html-parser instead of linkedom. The wrapper exposes the same DOM-like surface used by GitHub Trending and the reader preview (querySelector, querySelectorAll, closest, nextElementSibling, children, classList, textContent) plus a parentElement() accessor.
  • Worker bundle: 911.2 KiB / 210.4 KiB gzip → 327.5 KiB / 87.9 KiB gzip (64% smaller, and below the pre-upgrade 585.9 KiB).
  • Parse benchmark on a real 248 KB page (parse + six representative selector queries): 7.4 ms → 3.6 ms median.
  • Removed the now-unused DOM lib from tsconfig.json and simplified the Workers Cache typings.
  • Added core/test/dom.spec.ts covering body selection, fragments, and parent traversal.

Measured impact

Cold mobile browser load (Fast 4G, 4x CPU, service worker cleared):

Metric Before After
LCP 454 ms 294 ms
Render delay 288 ms 129 ms
Render-blocking requests 2 0
Forced reflow at startup 46 ms 0
Initial network requests 11 8

Desktop cold LCP measured at 43 ms.

Verification

  • Clean npm ci
  • npm run typecheck (TypeScript 7)
  • npm test (Vitest 5: 85 passing on Node 26; CI uses Node 24, which is supported)
  • npm run db:migrate:local
  • wrangler deploy --dry-run
  • Live GitHub Trending parse: 13 items from a 562 KB page in 10.4 ms
  • Live preview extraction: GitHub README (104 blocks, 9 min read) and Hugging Face paper (byline, abstract, full-paper links, citations)
  • Browser end-to-end: preview panel rendered 73 child blocks with images, headings, paragraphs, byline, and reading time; preview heights/controls synced
  • Cold mobile trace: no render-blocking requests and no forced reflow
  • Docs updated: README.md, docs/ARCHITECTURE.md, docs/DEPLOYMENT.md, docs/RUNBOOK.md

Notes

  • The home cache is five minutes; /api/items and personalization caches still invalidate from sync_state.last_success_at.
  • node-html-parser is now the only runtime dependency (besides the Worker platform bindings).
  • The parser runs only on refresh and preview invocations, not on home-page requests.

🤖 Generated with Claude Code

- Inline style.css and the pre-paint theme bootstrap into the server-rendered
  HTML, removing both render-blocking requests on first load
- Edge-cache GET / per URL for five minutes via the Cache API, keyed by
  APP_VERSION so deploys invalidate it; skip the cache in local dev
- Reduce home rendering from five sequential D1 reads to two parallel reads
  and parallelize the dashboard/health queries
- Add immutable caching for versioned static assets; bump the service-worker
  shell cache and stop precaching the now-inlined assets
- Remove the startup forced reflow in preview action placement
- Deduplicate favicon requests and add a buildErrors contract test

Co-Authored-By: Claude Code <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🔎 Cloudflare preview: https://f0419adc-feedreader.phatpham9.workers.dev

Uploaded from 6a4a4e59a8b7269c42bb3b696c52548095cc2b66. This is a Worker version preview — it shares the production D1 database, so it reads/writes real data; it does not receive cron-triggered refreshes.

- @cloudflare/workers-types 4.20260621.1 -> 5.20261113.1
- typescript 5.9.3 -> 7.0.2
- vitest 3.2.6 -> 5.1.0
- wrangler 4.103.0 -> 4.161.0
- linkedom 0.18.12 -> 0.18.15

npm audit drops from 12 vulnerabilities (2 critical, 8 high, 1 moderate,
1 low) to 0.

Verified with a clean npm ci, typecheck, 83 tests, local D1 migrations,
wrangler deploy --dry-run, and a dev smoke test including source parsing
and article-preview extraction.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@phatpham9 phatpham9 changed the title perf: inline critical assets and edge-cache the home page perf: inline critical assets, cache the home page, and upgrade dependencies Nov 13, 2026
- Swap the DOM parser used by GitHub Trending and the reader preview for
  node-html-parser 9.0.7; keep the DOM-like surface behind core/sources/dom.ts
- Shrink the Worker bundle from 911.2 KiB / 210.4 KiB gzip to
  327.5 KiB / 87.9 KiB gzip
- Parser benchmark on a 248 KB page: 7.4 ms -> 3.6 ms median (parse + queries)
- Drop the now-unused DOM lib from tsconfig and simplify the Cache typings
- Add wrapper tests for body selection, fragments, and parent traversal

Verified with 85 tests, typecheck, a live GitHub Trending parse, live GitHub
and Hugging Face preview extraction (including paper byline/links/citations),
browser preview rendering, and a cold mobile trace (LCP 294 ms, no
render-blocking requests, no forced reflow).

Co-Authored-By: Claude Code <noreply@anthropic.com>
@phatpham9 phatpham9 changed the title perf: inline critical assets, cache the home page, and upgrade dependencies perf: inline critical assets, cache the home page, and slim the Worker bundle Nov 13, 2026
@phatpham9

Copy link
Copy Markdown
Member Author

End-to-end verification after replacing linkedom

  • Deployed preview home: 200, inline <style>, no external stylesheet request, Cache-Control: public, max-age=0, s-maxage=300
  • Fresh GitHub README preview (astral-sh/ruff): 120 blocks rendered with headings, images, paragraphs, lists, quotes, and code
  • Fresh Hugging Face paper preview (2611.06518): byline detected, abstract/heading/list blocks returned
  • Live GitHub Trending parse: 13 items from a 562 KB page in 10.4 ms
  • Browser preview panel: 73 child blocks rendered with images, headings, paragraphs, byline, reading time, and synced header/footer heights
  • Cold mobile trace: LCP 294 ms, no render-blocking requests, no forced reflow
  • CI: typecheck-test-and-migrations ✅, preview ✅
  • npm audit: 0 vulnerabilities; npm ls linkedom is empty

🤖 Generated with Claude Code

@phatpham9
phatpham9 merged commit 4037c96 into main Nov 13, 2026
3 checks passed
@phatpham9
phatpham9 deleted the perf/first-load-caching-deps branch November 13, 2026 02:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant