Micro App: Split, SSR, SEO, Gateway

Canonical living examples, both extracted 2026-08 — read the real files, this skill records the decisions and landmines, not copies of the code:

• apps/workbench (/verify, /acceptance) — all code in this repo, builds and deploys from OSS CI.
• apps/share (/share/t/:id, /share/page/:id) — renders Cloud-only surfaces, so it builds and deploys from lobehub-cloud CI. See §1b before touching it.
• apps/auth (/signin, /signup, …) — the SSG variant: ssr: false + prerender, so the worker carries no React at all (7KB). 18 locales x 4 routes of prerendered documents. Also renders Cloud-only surfaces (§1b). See §3b.

Hosting

One app, two serve paths. Do not mix them.

generateSpaTemplates skips a missing dist/<name> HTML unless <NAME>_REQUIRED=1. Cloud must skip. Docker must require.

Do not revive Cloud SPA_TARGET=<name> Vite builds or a /spa-<name> middleware rewrite.

The Docker chain per app, all five links or the route is dead: root build:docker script → copySpaBuildCore.ts target entry (dist/<name> → public/_spa-<name>) → spaHtmlPaths.ts resolver + generateSpaTemplates block → src/app/spa-<name>/[locale]/[[...path]]/route.ts → middleware rewrite (src/libs/next/<name>Routes.ts + define-config.ts) plus the path in src/proxy.ts's matcher and, for public pages, in isPublicRoute.

Self-hosted loses per-page SSR. The Next shell serves the built SPA HTML with a brand OG card and noindex, nofollow; per-subject title/OG only exists in the Worker build. That is the accepted trade, not a bug to chase.

Dev shells — a 200 that lies. A /spa-<name> handler may only call fetchViteDevTemplate('/index.<name>.html') if that file exists at the repo root (workbench has one; it differs from apps/<name>/index.html only in the entry path, which must point at /apps/<name>/src/entry.tsx). Miss it and Vite's HTML fallback answers 200 with the main SPA shell — the micro app never loads, nothing errors, and the main SPA no longer has those routes. An app developed against its own Vite server (share: dev:spa:share) carries no dev branch at all. scripts/spaDevShells.test.ts guards both directions.

Crossing from the main SPA

Only markdown internal entity links leave the main SPA (InternalEntityLink → window.location.assign when shouldHardNavigateToWorkbench). Link and useWorkspaceAwareNavigate stay in-router. Electron never hard-navs (portal). Do not add a __WORKBENCH__ Vite define — the helper keys off the path (and skips Electron).

Share needed none of this: the only producer builds an absolute URL for copy/open (${appOrigin}/share/t/${id} in SharePopover), which is already a hard navigation. Before deleting src/routes/<x>/**, grep for in-router links to those paths — a surviving Link lands on the main SPA's 404. Then drop the routes from desktopRouter.config.tsx / mobileRouter.config.tsx and update desktopRouter.sync.test.tsx + routeScope.test.ts.

1. Splitting & Artifacts

App layout (apps/<name>/):

app/            # RR framework mode: root.tsx, routes.ts, entry.server.tsx, routes/, lib/, stubs/
workers/app.ts  # worker entry: API reverse proxy + createRequestHandler
src/            # app-owned features/shell (may coexist with a legacy SPA entry)
vite.config.rr.mts   # RR pipeline; legacy vite.config.ts can coexist (RR CLI: -c vite.config.rr.mts)
wrangler.jsonc  # name, account_id, nodejs_compat, vars (API base / app home)
staticCssOptions.mjs # ONE source for static-css hrefTemplate (vite plugin + emit + dev middleware)

Reuse main-src code via @/* deep imports + Vite 8 native resolve.tsconfigPaths: true (the vite-tsconfig-paths plugin breaks dev SSR module-runner resolution; the app's tsconfig include must cover app/). Stack: @react-router/dev@8 + @cloudflare/vite-plugin

• repo Vite 8 (rolldown) — officially compatible.

SSR bundle weight is the whole battle. Main-src imports drag the app universe (store web → chat/agent/electron). Tools and cuts, in order:

Share's cuts took SSR from 9.84MB → 1.78MB gzip. Two build-level snags worth knowing: resolve.dedupe must include @lobehub/ui (the builtin-tool-* packages declare a loose ^5 and resolve to an older copy whose base-ui lacks components the app renders → MISSING_EXPORT: Alert), and a *.client module needs its own SSR-env stub so the hydration gate does not drag the gated tree into the worker anyway.

Products: build/client (assets → CDN), build/server (worker; deploy with wrangler deploy --config build/server/wrangler.json). Budget: worker gzip ≤ 10MB paid.

CI affected-detection: build emits build-inputs.txt (module-graph file list, gitignored); the deploy workflow diffs changed files against the manifest from the last successful run's artifact (carry-forward on skip), plus meta triggers (app dir, plugins/vite, lockfile, tsconfig, glob dirs). New import.meta.glob patterns in shared code need a new meta trigger — the one manual rule. See apps/workbench/scripts/should-build.mjs + .github/workflows/deploy-workbench.yml; the overlay-hosted variant is lobehub-cloud's scripts/shouldBuildShare.ts + .github/workflows/deploy-share.yml (§1b).

PR-time verify is a separate workflow per repo that can change the artifact — deploy ownership (§1b) does not decide verify ownership. Each verify builds the worker, uploads a non-deployed preview version (wrangler versions upload --preview-alias, dry-run when secrets are absent), enforces the 8MB-gzip guard, and comments the preview URL behind an HTML marker (never --edit-last — other workflows comment as the same bot). Workbench: one repo, one verify-workbench.yml. Share: both repos, because either side's change flows into the deployed worker — OSS verify-share.yml + cloud verify-share.yml.

Previews upload to a sibling Worker, never to the production script. Cloudflare only rolls back to the 100 most recently uploaded versions of a script, and preview uploads count: at share's PR rate (10 uploads in under an hour on a busy day) every real deployment left the window within a day, which broke the gateway admin's (鳥居番) rollback list. So every verify passes --name lobehub-<name>-preview, and the production script's version list holds only deployments. Two consequences: the preview Worker must exist before the first upload (wrangler versions upload refuses a never-deployed script — bootstrap it once with wrangler deploy --name lobehub-<name>-preview from any stub; the next upload replaces it), and the preview API token must be allowed to edit the -preview name. Preview URLs are then https://<alias>-lobehub-<name>-preview.lobeobjects-tg.workers.dev, and VITE_CDN_BASE must point at that same origin. Alias namespaces must not collide on the shared preview worker: OSS uses pr<N>, cloud uses cloudpr<N>. Manifest source differs by what the repo can read: cloud verify borrows the deploy's share-deploy-state artifact (same repo); OSS verify cannot read cloud artifacts, so it self-bootstraps from its own last successful run's share-build-inputs (first run always builds).

1b. When the surface renders Cloud-only code

lobehub-cloud includes this repo as a submodule at lobehub/ and shadows it path-by-path through tsconfig paths (@/business/* → ./src/business/* then ./lobehub/src/business/*; @/* → ./src/* then ./lobehub/src/*). Split by ownership, not by which repo is handy:

apps/auth is the cheap case: because ssr: false ships no render graph, the Cloud overlay (BusinessAuthProvider → Turnstile + referral) added one chunk and 0 extra SSR stubs — measured at 585.7KB gz eager vs 587.3KB for the open-source build, with byte-identical markup. Do not assume that; apps/share needed 8.2MB of stubbing. Measure per app.

The RR config is a factory so both hosts share one pipeline: apps/share/vite.config.shared.mts exports createShareRrConfig({ appRoot, extraSsrStubs, repoRoot, resolvePlugins, staticCss }), and the OSS vite.config.rr.mts is a thin caller reading SHARE_TSCONFIG_PROJECT / SHARE_EXTRA_SSR_STUBS. Cloud fills both in scripts/shareApp.ts and drives the submodule app through scripts/{buildShare,devShare,deployShare,shouldBuildShare}.ts.

Landmine — the overlay silently doesn't apply. Vite 8's native resolve.tsconfigPaths resolves against the tsconfig nearest each importer, so submodule files resolve through the submodule's own tsconfig and the host overlay is lost. The build still succeeds and ships the open-source fallback surfaces (for share: a blank page). An overlay build must use the vite-tsconfig-paths plugin pinned to the host tsconfig and switch the native one off (tsconfigPaths: !resolvePlugins). Both settings are right in their own context — native for the standalone build, plugin for the overlay build. Verify by grepping build-inputs.txt for a Cloud-only file.

Whoever's code must be inside the artifact owns the build. Share deploys from lobehub-cloud (.github/workflows/deploy-share.yml), not OSS. Never add a deploy workflow to a repo that can only produce the fallback.

OSS PRs can still verify with the real overlay. Same-repo OSS PRs clone the overlay repo @ HEAD via .github/actions/business-overlay (the clone+overlay step extracted from desktop-build-setup: overlay files land in $GITHUB_WORKSPACE/.., which works because the repo is named lobehub so the checkout already sits at the submodule path), then cd .. && pnpm install and run the overlay repo's own bun run build:share — the tsconfig / stub knowledge stays over there. The OSS workflow never hardcodes the private repo name: it comes from the Actions repository variable OVERLAY_REPOSITORY; the token reuses the pre-existing LOBEHUB_CLOUD_TOKEN secret (deliberately not renamed — the desktop release workflows already reference it, and a rename would mean reconfiguring the org secret). When either is unset (fork PRs always), the workflow falls back to the OSS-stub build + wrangler dry-run as a pure compile/size guard. Keep new public-facing CI wording on the neutral "business overlay" vocabulary — the older desktop release workflows still leak the internal naming and are the known remaining exception. One trap: an overlay build's build-inputs.txt is overlay-root-relative (repoRoot = dirname(SHARE_TSCONFIG_PROJECT)), so OSS files appear as lobehub/src/... — strip that prefix before exact-matching against the OSS repo's own diff (sed 's#^lobehub/##' in the verify workflow); the meta triggers already match both spellings.

Cloud affected-detection needs submodule history: a bump is a single lobehub entry in the host diff, so the workflow runs git -C lobehub fetch --unshallow and compares the previous submodule SHA (carried in the state artifact) before diffing against build-inputs.txt.

Re-run the module trace in the Cloud build — the overlay adds chains OSS never sees (ShareAppShell → @/store/serverConfig/Provider → … → @/store/workspace → workspaceBootstrap → @/store/home → @/store/chat cost 8.2MB gzip until stubbed).

Merge order: OSS PR → submodule bump → Cloud PR. Until the OSS PR lands, anything deployed from a local submodule mirror is not reproducible from any commit — say so when handing over.

2. Deploy: CDN Assets + Worker

Assets follow the cloud convention (resolveViteBase): stable prefix, no version stamp — VITE_CDN_BASE=https://web-assets.lobehub.com/<name>/; content-hashed filenames make uploads incremental and immutable. The prefix axis is the app, nothing else: do not invent <name>-oss / <name>-cloud variants to separate build origins — hashed filenames already make one prefix safe for all of them. ASSET_S3_PUBLIC_DOMAIN is an origin; any path segment belongs on ASSET_BASE_URL instead. bun run deploy (see apps/workbench/scripts/deploy.ts) = build with CDN base → upload build/client/assets to R2 (web-assets bucket, LobeHub account) → wrangler deploy. R2 creds: 1Password Shared vault item "CI R2 - web-assets". CI injects repo secrets ASSET_S3_* (ACCESS_KEY_ID, SECRET_ACCESS_KEY, BUCKET, ENDPOINT, REGION, PUBLIC_DOMAIN). Local bun run deploy can fall back to MOBILE_S3_*. Never echo values.

Worker responsibilities beyond SSR: reverse-proxy /api|/oidc|/trpc|/webapi to WORKBENCH_API_BASE (standalone mode; behind the gateway the browser hits the apex and the gateway routes API to app instead), and redirect / + unknown paths to WORKBENCH_APP_HOME.

3. SSR

• Loader-side data: per-request tRPC client (httpLink + superjson + forwarded cookie header, base from wrangler vars via cloudflareContext) — the browser lambdaClient is SSR-stubbed. Inject into SWR with <SWRConfig value={{ fallback: { [unstable_serialize(key)]: data } }}>; key must equal useClientDataSWR's (augmentKey passes through when workspaceId is null).
• isLoading && !data: with SWRConfig fallback, isLoading is true during mount revalidation — a bare if (isLoading) swaps SSR content for a spinner after hydration.
• i18n: narrow to the namespaces the app renders; root loader preloads locale resources, i18n inits sync (initAsync: false) with bundled resources; SSR env stubs the shared glob loader to only its namespaces (full glob = every locale × ns as worker chunks).
• CSS three layers: lobe-ui static-css (antd probes + theme vars, hrefTemplate from the shared options file; emitted as hashed files, dev served by config middleware) → antd-style extractStaticStyle(html, { includeAntd: false }) for emotion → buildInlineAntdStyle(cache, { styleKeys }) fallback. Non-streaming render (await stream.allReady) so extraction is complete.
• <html suppressHydrationWarning> — next-themes stamps data-theme pre-hydration.
• Time-dependent output must be client-gated: relative timestamps and anything else the server and client compute differently belong behind a useHydrated() (useSyncExternalStore) check, not in the SSR pass.
• Skeletons must not swallow SSR'd chrome — and must hold its position. A list that flips to a skeleton on mount blanks the server-rendered header with it: render the header slot in the skeleton branch too. Presence is not enough — every phase (no-JS SSR fallback, post-hydration skeleton, settled list) must put that chrome in the same layout container as the final render, or the page jumps sideways when JS lands. Share's hero shipped left-flush while the settled list centered it in a min(960px, 100%) column, twice: the SSR fallback rendered ShareHero bare, and ChatList's showSkeleton branch rendered headerSlot outside WideScreenContainer. Verify by measuring the element's getBoundingClientRect().x across all three phases (stall the messages request to pin the skeleton phase), not by eyeballing one screenshot.
• Preload the error namespace, not just the render ones. The boundary shows exactly when a chunk failed to load — precisely when the client can no longer fetch a dictionary — and an untranslated boundary prints raw keys (error.title…). Cost for share: +6.3KB gzip/document.
• Prefilling a virtualized list: virtua caches measured sizes by index, so a truncated prefill that later grows misaligns every row. Prefill the whole list or none of it.

3b. Prerendering instead of SSR (ssr: false)

When every page is config-free at render time, ssr: false + prerender drops the whole SSR bundle-weight battle: no stubs, no client gates, and the worker is a static picker. apps/auth's is ~7KB — it resolves the locale, fetches one document out of the assets binding, and swaps a window.__SERVER_CONFIG__ placeholder for the deployment's config.

• Runtime config cannot be baked. The build has no deployment's env, so the document is prerendered config-free and the worker injects it. Anything that reads it must be hydration- gated (useIsHydrated), or the first client render diverges from the document.
• Audit what actually needs to travel that way — most of it does not. The hydration gate applies to the whole injected object, so every value routed through it is a value missing from the prerendered HTML. In apps/auth the config carried 11 fields; the pages read 6, and the most visible one was in the wrong layer entirely: enableBusinessFeatures is a build-time constant (@lobechat/business-const, false open-source / true in Cloud via a pnpm override) that was being round-tripped through the server, and with it the SSO provider list — itself a hardcoded array in the Cloud overlay. Reading the constant directly instead put Google/GitHub/Apple into the static document. featureFlags, enableMarketTrustedClient, telemetry and aiProvider had zero consumers and were dropped from the endpoint, which is public and unauthenticated. Do this audit before accepting "config-dependent UI pops in after hydration" as the cost of prerendering.
• Prerendering turns every localStorage read during render into a hydration bug. A returning user's stored state (useState(readStored)) makes the first client render disagree with a document that was built without it — apps/auth hit this twice, on the terms checkbox and on the "last used" provider badge, both of which also reorder the buttons. Move them to useState(empty) + useEffect. A fresh browser will not reproduce it; seed the keys and reload.
• The config needs an endpoint. A worker has no access to the app's env; apps/auth reads GET /webapi/auth/spa-config (public, s-maxage) through the API base and tolerates failure by leaving the placeholder in place.
• Landmine — one document per locale must live at the canonical path. Prerendering /:locale/signin and serving it at /signin looks like it works and silently breaks hydration: React Router matches the plain route, finds no context for the prefixed route id, and React re-renders the whole document — leaving two copies of the page in the DOM, with no console warning. Only the second one is visible, so a screenshot looks fine; count document.querySelectorAll('form') to catch it. The fix is one build pass per locale (AUTH_PRERENDER_LOCALE → environments.ssr.define), each prerendering the same canonical paths, with the non-default passes' documents folded into build/client/__i18n/<locale>/. Keep the locale out of the client define so every pass emits byte-identical assets — scripts/build.mjs asserts that by resolving each copied document's asset refs against the default build.
• The matrix costs build time, not bytes — and it parallelizes. apps/auth runs all 18 locales for 73 documents and 17.8MB in build/client, with no change to first load (640.8KB gz over the same 34 eager files: the per-locale dictionary chunks are lazy and each document carries only its own). The non-default passes share nothing and write to their own build-<locale>, so they fan out: 3m05s sequential → 44s at 6 concurrent on 16 cores. Each pass costs about two cores; past ~6 it stops paying (9 concurrent measured 42s, with per-pass time rising 12s → 16s). AUTH_BUILD_CONCURRENCY overrides the min(6, availableParallelism() - 2) default, which lands on 2 for a 4-vCPU CI runner — budget ~2min there, and mind that NODE_OPTIONS=--max-old-space-size applies per child. If that is still too slow, the remaining move is one build plus N renders against build/server/index.js with the locale threaded through entry.server.tsx — that trades the build-time define for request state, so it needs AsyncLocalStorage or strict sequencing. Verify RTL locales (ar, fa-IR) in a browser — they exercise the antd direction path that no LTR document touches.
• The prerender list is loaded by plain Node (react-router.config.ts), so it cannot import anything alias-resolved and has to be a literal array. Guard it against the dictionaries on disk in the build script, or a newly translated locale silently prerenders as English.
• i18n must be synchronous for the served locale. A resources-to-backend fetch renders English first and swaps a tick later, which is a hydration mismatch against a prerendered zh-CN document. Bundling every locale into the client instead costs a lot (auth: 63KB gz of dictionaries, eagerly modulepreloaded on every route), so apps/auth inlines only the served locale into the document as <script type="application/json"> and keeps the others behind an on-demand backend for the language switcher. Weigh it: that moved 44KB gz off the JS path but put 22KB gz onto the document, which is the one thing first paint waits for, and the dictionary is now re-sent per document instead of cached once. A per-locale hashed JS file loaded by a blocking script would beat both; nobody has built it yet.
• The client build must stay locale-agnostic for the one-pass-per-locale scheme to share assets, so anything that reads the dictionaries needs a server/client twin: the prerender module holds every bundle, the .client twin reads the document's inlined JSON, and vite.config.shared.mts swaps them per environment. meta() runs on both sides — it goes through the same twin, not a second copy of the strings.
• resolve.noExternal: true on the ssr env, build only. The prerender pass runs the built server bundle through plain Node, which rejects the extensionless directory imports some published es/ bundles ship (@lobehub/fluent-emoji). Setting it for serve too breaks the dev module runner on inlined CJS (module is not defined, then require is not defined) — and leaving it off leaves react-router dev 500ing on that same directory import. Known gap: apps/auth's dev server does not run; the working local loop is bun run build && wrangler dev.

RR v8 gotchas (docs/templates still say v7):

4. SEO

One shared builder (app/lib/seo.ts → buildPageMeta): title, description, robots, og:title/description/type/site_name/locale (underscore form)/image(+alt), twitter card set. Rules: leaf meta fully replaces root meta — every leaf returns the whole set; og:image must be an absolute URL (reuse landing's https://lobehub.com/assets/cao-og.webp); dynamic title/description come from the route loader (subject title · BRANDING_NAME, requirement text truncated ~200 chars).

5. Gateway Routing (torii, ../lobehub-gateway)

Config = KV config:lobehub.com, mirrored in config/entrypoints/lobehub.com/<env>.json. To add a micro app:

1. targets.<name> = worker hostname (must be cross-zone, e.g. *.workers.dev; https).
2. targetPolicies.<name> — cookies if SSR loaders need the .lobehub.com session forwarded; none for public-only; all adds Authorization. Add "locale": "query" when the app reads ?hl= (share does).
3. rules — first-match path prefixes ({ "match": "/acceptance", "target": "<name>" }). Leave /trpc unruled: it falls to default (app) so browser API calls stay same-origin authenticated. .data suffix is normalized before matching.
4. Validate: bun run test in the gateway repo (invariant suite reads the mirror).
5. Staging: bun scripts/torii.ts push --env staging --expect <fp> (needs TORII_ACCESS_*), or poke staging KV directly (wrangler kv key put --namespace-id <staging CONFIG ns>) — README-sanctioned. Prod writes only via the Toriiban (鳥居番) admin Promote button: torii.ts promote prints the exact delta and refuses to write, and push --env prod --confirm-prod exists but bypasses a deliberate human gate — don't. Before promoting, pull --env prod (repo mirrors go stale — a mirror-vs-live diff is not drift), run the invariant suite, and re-run verify --env staging.
6. Verify with staging debug headers: x-torii-target / x-torii-decision per request, and test document + .data + unaffected routes.
7. Rollback and previews live in 鳥居番's target detail pane, in a Worker card that every target whose host is in the gateway repo's bindings.ts gets for free. Releases lists the production script's Cloudflare deployments; a row is only rollbackable while its version is within Cloudflare's 100-upload window — which is the reason previews stay off the production script (§1). Previews lists the -preview Worker's versions (PR label and actor come from the --message stamp) with Open and, under staging, Set override, which writes the preview host into the target's targetOverrides immediately (a saved, history-recorded config write — no editor Save). Adding a micro app to bindings.ts is therefore part of wiring it into the gateway.

Landmine (fixed 2026-08, stay aware): the lobehub-com react-router-data plugin owns .data protocol affinity for the landing pair; it consults resolveRule and lets other targets' .data fall through — if a future entrypoint clones that plugin, keep the fall-through.

Checklist for a new micro app

1. Decide ownership first (§1b): does the surface render Cloud-only code? That fixes which repo builds, deploys, and holds the extra SSR stubs.
2. Scaffold apps/<name> (copy workbench/share shapes); routes + root + entry.server + worker.
3. Build, run the module trace, cut SSR weight (gate/stub/slot/deep-import) until gzip sane — in the overlay repo too, if there is one.
4. Wire CDN deploy (deploy.ts, stable _<name>/ prefix) + wrangler vars + redirects, plus a PR-time verify workflow in every repo whose changes reach the artifact (§1 PR-time verify — preview version on the bootstrapped lobehub-<name>-preview Worker, size guard, non-colliding alias namespace).
5. Loader data + SWR fallback + meta builder + i18n narrowing (+ error); verify with /trpc-blocked browser run (content must survive) and view-source (SSR content + meta present).
6. Deploy worker; verify workers.dev standalone (API proxy, / redirect).
7. Gateway: target + policy + rules on staging KV; curl matrix with x-torii headers; promote.
8. OSS Docker: all five links in the Hosting section, plus the removal sweep from the main SPA.
9. Cloud Next: no Vite target, no /spa-<name> rewrite, no _spa-<name> CDN upload.

Verifying, before you tell anyone it works

Build success proves nothing about what rendered. Each of these produced a real defect that a green build hid: the overlay resolving to OSS stubs, the dev shell answering 200 with the wrong app, an edit that silently no-op'd because the anchor string had drifted (deployed a 500 — so: build → local wrangler dev → browser → then deploy), and a "fix" asserted from the source instead of the page. Prove the Docker chain by running build:spa:<name> + <NAME>_REQUIRED=1 build:spa:copy and asserting every asset the generated template references exists under public/; prove the SSR page by viewing source, not by reading the loader.