Repository navigation
Load API reference sidebar trees once per package or module - #2213
Conversation
Each C# package/type/member-kind page now server-renders only the search
link, package overview and the current type's member-kind links. The full
package tree is emitted once per package as /reference/api/csharp/{pkg}/sidebar.json
and swapped in on the client by cloning the spine's own SidebarSublist
markup, reusing Starlight's sl-sidebar-state persistence. The C# landing
sidebar now links to packages instead of embedding every tree.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
TypeScript and Go module pages keep their server-rendered spine (search,
module overview, current item/member and its section anchors). The full
module catalog, grouped like the module overview, is now emitted once per
module as /reference/api/{typescript,go}/{module}/sidebar.json and swapped
in by the shared api-sidebar-tree loader used for C#.
The loader splices the spine's current-page group (with its section
anchors) into the tree in place of the matching entry, keeps overview
section anchors, and assigns stable sl-sidebar-restore indices so open
groups persist across pages in a package or module.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Combined validation: real
|
| Before | After all four PRs | |
|---|---|---|
Ev2ServiceArtifactsRoot/Images/aspiredev.tar.gz |
~4 GB | 1.76 GB |
| Built HTML pages | 38,344 | 29,134 |
Site output (dist) |
9.8 GB | 3.73 GB |
wwwroot in image |
n/a | 3.73 GB originals + 0.68 GB .br |
The container starts in 11 s, /healthz returns 200, and idle memory is about 2 GB, likely from the 134 MB staticwebassets.endpoints.json.
Testing against the container
- Layout check: 35 representative layouts (docs, splash, hub, 404,
/de/fallback,/ja/translated, C#/TS/Go API landing, package, type and member pages) on desktop and mobile. Every page returned the expected status, with no failed requests and no page errors. - Full Playwright suite,
CI=1 bunx playwright test, all 3 projects, reusing the container on :4322: 1,632 passed, 5 failed, 2 flaky, 107 skipped. Failures are triaged below. - Manual testing of the running container found no issues.
This PR: C# pages drop about 250 KB each (for example the kubernetes member page went from 437 KB to 117 KB). TS and Go now share the same lazy tree loader (data-api-sidebar-tree-state=loadedchecked on every API layout;provisioning.networkloads 1,448 links). No failures attributed to this PR.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Pages now reference /reference/api/{lang}/{name}/sidebar.json?v=<hash>,
where <hash> is the same apiDocumentCacheKey the payload carries, so the
edge can cache tree fetches indefinitely. The loader still resolves
relative hrefs against the sidebar.json folder (URL.pathname drops ?v=).
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
The sidebar assigns a category its first TypeScript or Go item's URL, causing navigation to replace the group with that item's spine and drop sibling links; the path resolution needs correction and regression coverage.
1 open issue
What changed in this PR
This PR reduces repeated API sidebar HTML on aspire.dev by rendering small per-page navigation spines and loading shared JSON trees. It reduces C# page size while adding full-catalog navigation to TypeScript and Go pages.
Changes:
- Adds one content-versioned sidebar JSON endpoint per package or module.
- Introduces a shared client loader that preserves current-page links, section anchors, and sidebar state.
- Expands unit and browser coverage for sidebar generation and navigation.
| File | Description |
|---|---|
src/frontend/tests/unit/ts-api-sidebar.vitest.test.ts |
Tests TypeScript catalog grouping. |
src/frontend/tests/unit/go-api-sidebar.vitest.test.ts |
Tests Go catalog grouping. |
src/frontend/tests/unit/api-sidebar.vitest.test.ts |
Tests C# spines and compact trees. |
src/frontend/tests/unit/api-sidebar-tree-src.vitest.test.ts |
Tests versioned tree URLs. |
src/frontend/tests/e2e/ts-api-sidebar.spec.ts |
Checks TypeScript tree loading and navigation. |
src/frontend/tests/e2e/go-api-sidebar.spec.ts |
Checks Go tree loading and navigation. |
src/frontend/tests/e2e/csharp-api-sidebar.spec.ts |
Covers C# spines, trees, filtering, and no-JavaScript access. |
src/frontend/tests/e2e/api-cross-language-navigation.spec.ts |
Checks destination trees after cross-language navigation. |
src/frontend/src/utils/ts-api-sidebar.ts |
Builds compact TypeScript catalog trees. |
src/frontend/src/utils/go-api-sidebar.ts |
Builds compact Go catalog trees. |
src/frontend/src/utils/api-sidebar.ts |
Generates C# spines, package links, and compact trees. |
src/frontend/src/utils/api-sidebar-tree-src.ts |
Resolves content-versioned tree URLs. |
src/frontend/src/pages/reference/api/typescript/[module]/sidebar.json.ts |
Emits each TypeScript module’s tree. |
src/frontend/src/pages/reference/api/go/[module]/sidebar.json.ts |
Emits each Go module’s tree. |
src/frontend/src/pages/reference/api/csharp/[package]/sidebar.json.ts |
Emits each C# package’s tree. |
src/frontend/src/pages/reference/api/csharp/[package]/[type]/index.astro |
Supplies the current type to the spine builder. |
src/frontend/src/pages/reference/api/csharp/[package]/[type]/[memberKind].astro |
Supplies the current type on member-kind pages. |
src/frontend/src/components/starlight/Sidebar.astro |
Connects tree loading to sidebar controls. |
src/frontend/src/components/starlight/api-sidebar-tree.ts |
Fetches and renders shared trees while retaining page navigation. |
Review effort: Balanced
| function nodePath(value: string | CompactSidebarNode[], baseHref: string): string | undefined { | ||
| if (typeof value === 'string') return normalizePath(resolveHref(value, baseHref)); | ||
| const first = value[0]; | ||
| return first && typeof first[1] === 'string' ? normalizePath(resolveHref(first[1], baseHref)) : undefined; |

Summary
Part of a series of PRs to reduce the size of the frontend container image. This PR moves the full API reference sidebar tree out of each page's HTML for C#, TypeScript and Go: every page server-renders only a small "spine", and the full tree loads once per package or module as JSON.
Before this change, every C# package, type and member-kind page rendered its package's entire sidebar tree. On
aspire.hosting.kubernetes/ingressbackendv1/properties/, that sidebar was about 255 KB, compared with about 81 KB of main content. The TypeScript and Go sidebars were already spines onmain, but they only offered a link back to the module overview, not the module's catalog.Changes:
src/utils/api-sidebar.ts): "Search APIs", the package Overview, and the current namespace and type with its member-kind links.ts-api-sidebar.ts,go-api-sidebar.ts): unchanged. "Search", the module Overview, and the current item and member, each with its section anchors./reference/api/{csharp,typescript,go}/{name}/sidebar.json, from asidebar.json.tsendpoint next to each language's[package]/[module]route.apiDocumentCacheKeyas the pages, so incremental builds still reuse them. As endpoints, they stay out of the sitemap.src/components/starlight/api-sidebar-tree.ts, wired up fromSidebar.astro): when the browser is idle, it fetches the JSON and builds the tree from the page's own sidebar markup, so styles and icons stay identical to Starlight's output.aria-current, opens its parent groups, and keeps Starlight's open-group state stable, so open groups and scroll position carry over between pages in the same package or module.Estimated savings:
/reference/api/csharp/about −2.7 MBdata-api-sidebar-treeattribute); the spine is unchangedaspire.hosting.azure.provisioning.network, 123 KB)For TypeScript and Go, the change adds full-catalog navigation without increasing page weight; it doesn't reduce their size. Most of TypeScript's 739 MB is page content plus page chrome repeated on every page, which other PRs in this series address.
Third-party links and affiliations
None
Validation
npx vitest run --config vitest.config.ts tests/unit/api-sidebar.vitest.test.ts tests/unit/api-route-props.vitest.test.ts tests/unit/ts-api-sidebar.vitest.test.ts tests/unit/go-api-sidebar.vitest.test.ts tests/unit/api-reference-components.vitest.test.ts tests/unit/api-cache-key.vitest.test.ts tests/unit/api-reference-routes.vitest.test.ts: passed (7 files, 45 tests).npx eslinton all changed.tssources and tests: passed.npx playwright test tests/e2e/csharp-api-sidebar.spec.ts tests/e2e/ts-api-sidebar.spec.ts tests/e2e/go-api-sidebar.spec.ts tests/e2e/api-cross-language-navigation.spec.ts --project=desktop-chromium --project=mobile-chromium, run againstastro dev: passed (22 tests).astro devon C#, TypeScript and Go overview, item and member pages: the full tree loaded (1,436 links for the largest TypeScript module), the current page was highlighted and its section anchors were kept, there were no duplicate links, open-group indices stayed stable across pages, and no page errors appeared.bun run buildwas not run locally; CI builds the site.