Skip to content

build(desktop): static export of the desktop renderer (P2.4a) - #127

Merged
7 commits merged into
mainfrom
claude/feat-p2-4-desktop-export
Nov 17, 2026
Merged

7 commits merged into
mainfrom
claude/feat-p2-4-desktop-export

Conversation

@HMarzban

Copy link
Copy Markdown
Contributor

Phase 2 P2.4a: the desktop renderer's static export (desktop local-first design §8.4, row P2.4; arch §3.1). The dev bridge and the local Playwright project are P2.4b, built after #121 and P2.1's use-yjs-document PR land.

What it does

  • bun run build:desktop (scripts/build-desktop.ts) writes out/ with NEXT_PUBLIC_APP_TARGET=desktop and output: "export".
  • next.config.ts switches three things on the literal flag: output, pageExtensions and headers().
  • app/icon.tsx is force-static.

How routes leave the export

The brief asked for this without the spike's file-renaming overlay. #115's measurements rule that out for some files, so I used two mechanisms.

Files Mechanism Why
app/api/**, llms.txt, pwa-icons/[id] route handlers renamed route.web.ts(x); desktop pageExtensions skip them pageExtensions works for route files
sitemap, robots, manifest, opengraph-image, apple-icon parked in .desktop-export-parked/ for the build Turbopack ignores pageExtensions for metadata files (S1). With force-static they'd put the manifest, og:image and apple-touch-icon tags into every desktop page (#115)
/privacy and /offline pages parked as well New finding: renaming a page to page.web.tsx drops the root layout's Inter font preload from its web HTML. Next 16.4.6's getPreloadableFonts strips only the last extension, so it looks up app/privacy/page.web in a font manifest keyed app/privacy/page. Measured: /privacy and /offline lost <link rel="preload" as="font">

Turning the metadata files into route.web.ts handlers with hand-written metadata would also change the web <head>: Next adds content-hash query strings to og:image, twitter:image, icon and apple-touch-icon. That fails the exit criterion.

The parking follows #115's rules:

  • park inside the checkout (EXDEV on Windows);
  • restore leftovers first;
  • restore in finally and on SIGINT/SIGTERM;
  • fail when a file is in both places.

next.config.ts also refuses a web build while anything is parked, so a SIGKILLed export can't ship a web build without its sitemap or privacy page.

The desktop export skips Next's own type pass. After a next dev run, .next/dev/types imports the parked pages. bun run typecheck already checks every file, desktop-only files included.

#117 follow-ups

  • SHELL_PATHS precaching /privacy: the desktop build never registers the service worker. The flag is compared in service-worker-registration.tsx, not in the worker, because sw-config.ts must not read process.env. Desktop chunks contain no registration (grep sw.js: 0 files, web: 1).
  • The desktop Playwright project in CI: next start can't serve a static export, so the project now runs on out/.
    • It is served by scripts/serve-desktop-export.ts with the app:// protocol handler's path rules.
    • Those rules live in desktop/shared/export-paths.ts for P2.5 to reuse: /about → about.html, RSC .txt under their exported names, /icon as image/png, unknown types and traversal refused. This covers the P2.4 hardening row.
    • A new test checks that every request the renderer makes is answered (pages, segment prefetch, RSC payload, icon) and none goes to a web-only route.
    • It is wired into nightly (desktop-renderer, on Linux, where releases build the renderer). It also checks git diff --exit-code -- app after the export.

Web build diff against main (1ed981e), both with NEXT_PUBLIC_BUILD_ID=baseline

Result
Route table (next build output) identical
.next/static chunks, every name and size identical (only Next's random build-id directory name differs)
server/app file list identical
app-path-routes-manifest, routes-manifest, next-font-manifest, app-paths-manifest identical
prerender-manifest (minus random preview keys) identical
sw.js byte-identical
HTML and RSC of /, /about, /privacy, /offline, /_not-found, _global-error identical apart from the build id and the /icon?<hash> cache-buster, which changes because icon.tsx's source gained force-static; the PNG is byte-identical

That is the "differs only in the route flags" exit criterion.

Verification

  • bun run build:desktop passes, and the output check passes. After the build, git status -- app is clean, including after a build that fails its type check.
  • bun run test: 1,567 pass.
    • New: desktop-export.test.ts (parking, leftovers, conflict, output check, every route handler under app/api, llms.txt and pwa-icons is route.web.*).
    • New: export-paths.test.ts (mapping, types, traversal).
    • New: service-worker-registration.test.ts.
  • bun run typecheck, ESLint and Biome (no new findings) pass. tests/unit/ci (workflow rules) passes with the nightly job.
  • Playwright chromium (--retries=1, against next dev and Hocus on spare ports with CI's limits): 523 passed, 22 skipped, 0 failed, 0 flaky. The renamed DELETE route answers 200 in dev.
  • Playwright desktop on the export: 3 passed.
  • local: not in this PR (P2.4b).
  • Everything was headless and on localhost.

Not in this PR

  • P2.4b: the window.tinydocy dev bridge (lib/platform/desktop/, NEXT_PUBLIC_DESKTOP_BRIDGE=dev), desktop/dev/storage-host.ts on MemoryDocStore, and the local Playwright project. They follow feat(platform): add local-session, the batcher and MemoryDocStore (P2.1b) #121 and P2.1's hook PR.
  • Upstream: the getPreloadableFonts multi-dot page extension bug is worth reporting to vercel/next.js. Not filed.

bun run build:desktop writes the static export to out/ with
NEXT_PUBLIC_APP_TARGET=desktop. Web-only route handlers become
route.web.ts(x), which the desktop page extensions skip. The five web
metadata files and the /privacy and /offline pages are parked in the
checkout for the build and put back: Turbopack ignores pageExtensions
for metadata files, and a page.web.tsx loses the root layout's font
preload on the web. next.config.ts refuses a web build while anything
is parked. The export fails if a web-only route, a web metadata tag or
the Windows segment layout reaches out/. icon.tsx is force-static.
The worker precaches web-only pages (SHELL_PATHS has /privacy) and the
desktop renderer loads from disk, so the target flag now turns
registration off, as NEXT_PUBLIC_SERVICE_WORKER=0 does.
desktop/shared/export-paths.ts holds the app:// protocol handler's path
rules for the shell to reuse: pages to .html, RSC payloads under their
exported names, the extension-less icon as image/png, unknown types and
traversal refused. scripts/serve-desktop-export.ts serves out/ with
them, the desktop project checks that every request the renderer makes
is answered, and nightly runs it on Linux.
After a next dev run, .next/dev/types imports the /privacy and /offline
pages, which the export parks, so the export failed its type check.
bun run typecheck already checks every file, desktop ones included.
@HMarzban

Copy link
Copy Markdown
Contributor Author

Merged origin/main (08b7663, batch #126) in 4289a54. The only conflict was CHANGELOG.md, and both entries are kept.

Re-checked against 08b7663 with the same NEXT_PUBLIC_BUILD_ID:

  • Identical: the route table; every .next/static chunk, by name and size; the server/app file list; the routing, font and app-paths manifests; prerender-manifest without its preview keys; sw.js.
  • HTML and RSC: every page matches, apart from the build id and the /icon?<hash> cache-buster. The PNG is byte-identical.
  • Tests on the merge: bun run test 1,700 pass. Typecheck, ESLint and Biome (0 errors) pass. The desktop export is valid, and git status -- app is clean afterwards. The desktop project passes 3 of 3.

Under a desktop-target next dev the web metadata files aren't parked,
and output: "export" made each of them a 500 that every page links.
The config is now a phase function; the web config object is
unchanged.
@HMarzban HMarzban closed this pull request by merging all changes into main in 29f6faf Nov 17, 2026
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