Skip to content

fix(api-reference): M-25047456 move the spec out of API page HTML - #1333

Merged
twosugar merged 1 commit into
mainfrom
fix/api-reference-spec-out-of-html
Nov 18, 2026
Merged

twosugar merged 1 commit into
mainfrom
fix/api-reference-spec-out-of-html

Conversation

@twosugar

Copy link
Copy Markdown
Collaborator

Merge Verdict

[APPROVE] — API page HTML drops from ~2.2 MB to ~136 KB and the <h1> moves from byte ~2,215,000 to ~115,000, inside Googlebot's 2 MB fetch window; behavior is unchanged.

2 files · +6 / -7 · api-reference layouts

Requirement: M-25047456 (sitemap coverage: none of the 486 /docs/api/* pages has been crawled by Google).


Summary

  • Root cause: ApiReferenceLayout.astro passed the whole openapi.yaml string as a prop to <ApiReference client:load>. Astro serializes island props into the page HTML, so every API page carried ~2.1 MB of spec before its content. Googlebot only fetches the first 2 MB (uncompressed) of an HTML document, so the <h1>, body and sidebar links never reached it.
  • ApiReference.tsx now imports ../../../openapi.yaml?raw itself (same pattern as QuotePermission.tsx / openapi-markdown.ts), and the rawYaml prop is removed. The spec ships once in the hashed island chunk, which only the API pages load and browsers cache across pages.
  • Prerender output is unchanged apart from size: same content, title, description and 161 sidebar links per page.

Risk Analysis

Risk Level Mitigation
Other consumers of the removed prop ✅ ApiReferenceLayout.astro is the only place that renders <ApiReference>; rg finds no other caller
Spec leaking into non-API pages ✅ In the build, the spec marker exists only in assets/index.<hash>.js, referenced by the 486 API pages and by no docs / home page
Hydration mismatch 🟢 Prerender and client parse the same module-level string; the layout never filtered the spec by region / env
First-visit download 🟢 Roughly unchanged (gzip: 311 KB → 304 KB); later API pages drop from ~218 KB to ~16 KB each

Design Decisions

  • Module import over a fetched JSON file: the island still has the spec synchronously at hydration, so prerender and client render identically with no loading state; the browser caches the hashed chunk.
  • Keep parsing on the client as before: no change to parseSpec or to how the reference renders; this PR only moves where the bytes live.

Code Concerns

  1. [Needs Decision] Island chunk is itself over 2 MB (packages/api-reference/src/ApiReference.tsx:30)
    assets/index.<hash>.js is 2,164,371 bytes uncompressed. If Google's renderer truncates it, the island won't hydrate for the bot; indexing is unaffected because the static HTML already holds the full content. Splitting the spec per locale or shipping it pre-parsed would bring it under 2 MB — follow-up if we want the rendered view to match.

Verification

Check Result
bun run build:canary ✅ astro check 0 errors; 1405 pages indexed
API page HTML size (build) ✅ 483 pages, 126–164 KB; <h1> at most byte 123,344 across all 486 API pages
Page content in build ✅ 0 pages with wrong <h1>, missing title, or < 161 API links
Spec location in build ✅ only in the API island chunk; 0 non-API pages reference it
Canary deploy (open.longbridge.xyz, open-canary.longbridge.xyz) ✅ /docs/api/dividends 135,851 B / 137,013 B, <h1> at 114,104 / 115,204
Browser on canary + local preview of the build ✅ hydrates, in-app switch, back/forward, Try-it drawer; no hydration warnings
oxlint ✅
Independent review (fresh subagent) ✅ no bugs; chunk size noted above
Google crawl / sitemap coverage 📋 Needs verification after release (GSC)

Conclusion basis

  • Verified: canary build output scanned with scripts; local astro preview and both canary hosts measured with curl and checked in the browser.
  • Inferred from code, not tested: Code Concern 1 (renderer behavior on a > 2 MB script).
  • Not covered: build:release and the cn region build were not run.

🤖 Generated with Claude Code

… page HTML

ApiReferenceLayout passed the whole openapi.yaml to <ApiReference client:load>
as a prop, so Astro serialized ~2.1 MB of spec into every /docs/api page.
The <h1> landed at byte ~2,215,000, past Googlebot's 2 MB fetch cutoff, and
none of the 486 API pages got crawled.

ApiReference now imports openapi.yaml?raw itself and the rawYaml prop is gone,
so the spec ships once in the hashed island chunk (only API pages load it).
API page HTML drops to 126-164 KB with the <h1> before byte ~124 KB.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@twosugar
twosugar merged commit 640b74a into main Nov 18, 2026
2 checks passed
@twosugar
twosugar deleted the fix/api-reference-spec-out-of-html branch November 18, 2026 07:15
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