Repository navigation
Add incremental builds to the hybrid API architecture - #1698
Closed
David Pine (IEvangelist) wants to merge 41 commits into
Closed
David Pine (IEvangelist) wants to merge 41 commits into
David Pine (IEvangelist) wants to merge 41 commits into
Conversation
Contributor
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
David Pine (IEvangelist)
added
the
ci:incremental-pilot
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
David Pine (IEvangelist)
added
ci:incremental-pilot:identity
David Pine (IEvangelist)
changed the title
David Pine (IEvangelist)
added
ci:incremental-pilot
David Pine (IEvangelist)
added
ci:incremental-pilot
David Pine (IEvangelist)
force-pushed
the
ievangelist-astro-incremental-builds
branch
from
October 19, 2026 13:37
4996f45 to
8aae54a
Compare
David Pine (IEvangelist)
changed the base branch from
main
to
ievangelist-hybrid-api-rendering
October 19, 2026 13:37
David Pine (IEvangelist)
added this pull request to stack #1911
October 19, 2026 13:37
David Pine (IEvangelist)
changed the title
David Pine (IEvangelist)
added
ci:incremental-pilot
David Pine (IEvangelist)
marked this pull request as ready for review
October 19, 2026 20:09
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Cache-key generation can persist degraded external-service outputs across subsequent builds.
2 open issues
1 file not reviewed
src/frontend/pnpm-lock.yaml: Generated file
What changed in this PR
Adds opt-in incremental prerendering on top of #1874’s hybrid architecture, while API detail routes remain on demand.
Changes:
- Adds cache partitioning, route keys, and deployment-identity stamping.
- Adds compatibility fixes and focused regression tests.
- Restricts artifact uploads to successful builds.
| File | Description |
|---|---|
src/frontend/tests/unit/twoslash-environment.vitest.test.ts |
Tests SDK declaration resolution. |
src/frontend/tests/unit/og-build-cache.vitest.test.ts |
Tests OG cache keys and exclusions. |
src/frontend/tests/unit/incremental-build.vitest.test.ts |
Tests caching, invalidation, and identity stamping. |
src/frontend/tests/unit/icon-safelist.vitest.test.ts |
Tests deferred icon safelist loading. |
src/frontend/tests/unit/dev-resource-catalog.vitest.test.ts |
Updates canonical-ID tests. |
src/frontend/tests/unit/build-performance.vitest.test.ts |
Updates upload-condition assertions. |
src/frontend/src/utils/og-build-cache.ts |
Generates OG cache keys. |
src/frontend/src/utils/dev-center/catalog-normalization.ts |
Uses canonical content IDs. |
src/frontend/src/types/incremental-build.d.ts |
Types the generated icon digest. |
src/frontend/src/pages/og/reference/samples/[sample].png.ts |
Adds sample-image cache keys. |
src/frontend/src/pages/og/[...slug].png.ts |
Adds documentation-image cache keys. |
src/frontend/scripts/build-incremental.mjs |
Launches opt-in incremental builds. |
src/frontend/pnpm-workspace.yaml |
Registers Astro compatibility patch. |
src/frontend/pnpm-lock.yaml |
Locks dependencies and patch hashes. |
src/frontend/patches/starlight-plugin-icons@1.1.6.patch |
Defers safelist evaluation. |
src/frontend/patches/astro@7.3.2.patch |
Normalizes Rolldown asset handles. |
src/frontend/package.json |
Adds build command and dependencies. |
src/frontend/config/twoslash.config.mjs |
Resolves declarations from frontend working directory. |
src/frontend/config/incremental-build.mjs |
Implements caching and identity stamping. |
src/frontend/astro.config.mjs |
Wires incremental mode into Astro. |
package.json |
Exposes root incremental command. |
.github/workflows/frontend-build.yml |
Gates artifact uploads on build success. |
Review effort: Balanced
| async getStaticPaths() { | ||
| const paths = await prerenderer.getStaticPaths(); | ||
| cacheableComponents.clear(); | ||
| const cacheablePaths = paths.map((path) => { |
| const paths = await prerenderer.getStaticPaths(); | ||
| cacheableComponents.clear(); | ||
| const cacheablePaths = paths.map((path) => { | ||
| const component = path.route.component.replaceAll('\\', '/'); |
David Pine (IEvangelist)
force-pushed
the
ievangelist-hybrid-api-rendering
branch
from
October 19, 2026 20:27
2f75c44 to
586d45e
Compare
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Wrap the default prerenderer using Astro's public hook, retaining metadata for keyed components while avoiding render scopes and response buffering for uncached docs. Preserve lifecycle receivers, image collection and response bytes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add ordinary cache-warm full-build controls and qualify OG asset invalidation and search cache recovery. Keep emoji-dependent cards uncached and production opt-out. Remove internal pilot details from the contributor guide. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Gate normal and pilot uploads on successful build steps, preserving reports after later test failures but not failed or cancelled builds. Recognize Astro's trailing slash on restored OG endpoints without broadening the allowed route families. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Print bounded mismatch counts and paths in the job log so failures remain diagnosable when build-gated artifact uploads are skipped. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Resolve Starlight through import.meta.resolve so Playwright can load the search suite when the package export has no CommonJS require condition. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Keep the Starlight ESM resolution fix surgical by restoring the file's existing formatting. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Use Starlight's canonical content entry ID directly so forced clean builds do not trip Astro's deprecated data.slug getter while generating the resource catalog. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Resolve the generated declaration bundle from the frontend project root so Astro's relocated prerender config continues to load it during forced-clean builds. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Capture Community Toolkit contributor responses under the lowercase repository URL used by the contributor cache so deterministic replay does not reject a case-only mismatch. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Port the custom mobile sidebar lifecycle to Starlight 0.42's native Popover API, preserve focus and responsive behavior, and restore homepage reveal contrast under Axe 4.13. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Record normalized client and prerender module hashes during the CI pilot so unexpected route invalidation identifies the changing dependency without weakening reuse or output checks. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Backport Astro's Rolldown asset placeholder normalization so unchanged font modules keep stable dependency hashes during incremental builds while 7.4.0 remains inside the seven-day release buffer. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Raise the isolated incremental qualification timeout to 240 minutes so the longest API-data scenario can complete the existing browser matrix after build, lint, and unit validation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Restore merge-resolved qualification behavior, remove the custom Pagefind cache, retain the upgraded page-actions patch, and adapt deterministic Pagefind finalization to hybrid output. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Keep the opt-in hybrid incremental implementation and focused correctness coverage while dropping benchmark workflows, comparison scripts, and determinism-only patches. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
David Pine (IEvangelist)
force-pushed
the
ievangelist-astro-incremental-builds
branch
from
October 19, 2026 20:29
2fe42e3 to
e89a7af
Compare
David Pine (IEvangelist)
removed this pull request from stack #1911
October 19, 2026 20:37
Member
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Important
This is the top layer of native stack #1911. #1874 targets
release/17.0; this PR targets #1874'sievangelist-hybrid-api-renderingbranch. The incremental enhancement depends on that hybrid architecture rather than maintaining a separate static API build path.Add an opt-in hybrid incremental build for the routes that #1874 still prerenders.
pnpm build:incrementalenables bothASPIRE_HYBRID_API_DOCS=1andASPIRE_INCREMENTAL_BUILD=1: API detail HTML and Markdown remain on-demand in the hybrid renderer, while Astro can restore unchanged documentation, landing-page, endpoint, and owned OG outputs indist-hybrid/client.The incremental wrapper supplies stable cache keys for prerendered routes. Its compatibility partition covers ordinary source, configuration, public assets, patches, package resolution, platform, Node version, and public build inputs. Generated API data is hashed separately so API landing pages expire when their data changes without invalidating unrelated static routes; the on-demand route catalog and server artifact are always rebuilt.
Deployment identity substitution is limited to Astro's prerender environment. Cached static HTML receives the current commit through equal-width byte stamping, while the on-demand server bundle retains the real commit value. Pagefind continues to run normally and is not cached or reused.
Reduced scope
Safety and rollout
data.sluggetter.Third-party links and affiliations
None.
Validation
Current stacked head:
e89a7af88d304139cbd4e2ccf0a10d1e7ce8c396.pnpm lintfromsrc/frontend- passed.pnpm test:unitfromsrc/frontend- passed: 89 files, 1,256 passed, one expected skip.git diff --check- passed.dotnet test tests\StaticHost.Tests\StaticHost.Tests.csproj --filter "FullyQualifiedName~HybridApiDocs" --nologo- previously passed: 39 tests.dotnet test tests\Aspire.Dev.AppHost.Tests\Aspire.Dev.AppHost.Tests.csproj --filter "FullyQualifiedName~HybridApiDocs" --nologo- previously passed: 7 tests.