Add incremental builds to the hybrid API architecture

.github/workflows/frontend-build.yml

@@ -120,6 +120,7 @@ jobs:
 
       # Validation has its own checkout so astro sync cannot dirty Lunaria's tree.
       - name: Build frontend
+        id: frontend_build
         env:
           MODE: production
           ASTRO_TELEMETRY_DISABLED: 1
@@ -152,21 +153,21 @@ jobs:
         run: node scripts/measure-build-output.mjs
 
       - name: Upload build diagnostics
-        if: ${{ always() && inputs.profile_build }}
+        if: ${{ inputs.profile_build }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: frontend-performance
           path: ${{ runner.temp }}/frontend-performance
           if-no-files-found: warn
           retention-days: 7
 
-      # Upload before the dist sanity-check so the artifact is always
-      # available for debugging, even when the check step fails.
+      # Upload only a successful build, before later checks so their failures
+      # don't hide an otherwise valid build artifact.
       # Note: `uses` actions ignore the job-level working-directory,
       # so the path is repo-root-relative (src/frontend/dist).
       - name: Upload build artifact
         id: upload_build_artifact
-        if: ${{ always() }}
+        if: ${{ !cancelled() && steps.frontend_build.outcome == 'success' }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: frontend-dist

package.json

@@ -7,6 +7,7 @@
     "dev": "pnpm --dir ./src/frontend run dev",
     "build": "pnpm --dir ./src/frontend run build",
     "build:skip-search": "pnpm --dir ./src/frontend run build:skip-search",
+    "build:incremental": "pnpm --dir ./src/frontend run build:incremental",
     "preview": "pnpm --dir ./src/frontend run preview",
     "test": "pnpm --dir ./src/frontend run test",
     "test:all": "pnpm --dir ./src/frontend run test:all",

src/frontend/astro.config.mjs

@@ -1,5 +1,6 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
+import { fileURLToPath } from 'node:url';
 import { unified } from '@astrojs/markdown-remark';
 import { sidebarTopics } from './config/sidebar/sidebar.topics.ts';
 import { redirects } from './config/redirects.mjs';
@@ -23,6 +24,7 @@ import starlightSidebarTopics from 'starlight-sidebar-topics';
 import starlightPageActions from 'starlight-page-actions';
 import buildTiming from './config/build-timing.mjs';
 import { contributorCacheIntegration } from './src/utils/contributors.ts';
+import { loadIncrementalBuildSettings } from './config/incremental-build.mjs';
 import UnoCSS from 'unocss/astro';
 import Icons from 'starlight-plugin-icons';
 import node from '@astrojs/node';
@@ -33,6 +35,18 @@ const modeArgIndex = process.argv.indexOf('--mode');
 const isSkipSearchBuild = modeArgIndex >= 0 && process.argv[modeArgIndex + 1] === 'skip-search';
 const outDir = process.env.ASTRO_OUT_DIR;
 const isBuildTimingEnabled = process.env.BUILD_TIMING === '1';
+const incrementalRequested = process.env.ASPIRE_INCREMENTAL_BUILD === '1';
+const isIncrementalBuild =
+  hybridApiDocs &&
+  incrementalRequested &&
+  process.argv.includes('build');
+if (incrementalRequested && process.argv.includes('build') && !hybridApiDocs) {
+  throw new Error('Incremental builds require the hybrid API documentation architecture.');
+}
+const mode = modeArgIndex >= 0 ? process.argv[modeArgIndex + 1] : 'production';
+const incremental = isIncrementalBuild
+  ? await loadIncrementalBuildSettings(new URL('.', import.meta.url), mode)
+  : undefined;
 const siteDescription = aspireProject.description;
 
 // Under `aspire run` the frontend dev server (Vite) and StaticHost are separate
@@ -58,7 +72,11 @@ const buildConcurrency = Number(process.env.ASPIRE_BUILD_CONCURRENCY) || 4;
 
 // https://astro.build/config
 export default defineConfig({
-  cacheDir: hybridApiDocs ? './node_modules/.astro-hybrid' : './node_modules/.astro',
+  cacheDir: incremental
+    ? fileURLToPath(incremental.cacheDir)
+    : hybridApiDocs
+      ? './node_modules/.astro-hybrid'
+      : './node_modules/.astro',
   ...(hybridApiDocs
     ? {
         outDir: hybridOutputDirectory(process.cwd(), outDir),
@@ -67,12 +85,18 @@ export default defineConfig({
         ...hybridApiCacheConfig(),
       }
     : outDir ? { outDir } : {}),
+  ...(incremental ? { experimental: { incrementalBuild: true } } : {}),
   vite: {
     define: {
       // Resolve filesystem-backed redirects before prerender modules are bundled.
       __ASPIRE_REDIRECT_PATHS__: JSON.stringify(Object.keys(redirects)),
       __ASPIRE_HYBRID_API_DOCS__: JSON.stringify(hybridApiDocs),
     },
+    ...(incremental
+      ? {
+          plugins: [incremental.privateIdentityPlugin],
+        }
+      : {}),
     ...(staticHostUrl
       ? {
           server: {
@@ -253,6 +277,7 @@ export default defineConfig({
     ...(isBuildTimingEnabled ? [buildTiming()] : []),
     aspireVersionPlaceholdersIntegration(),
     ...(hybridApiDocs ? [hybridApiDocsIntegration(redirects)] : []),
+    ...(incremental ? [incremental.integration] : []),
   ],
   build: {
     concurrency: buildConcurrency,