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.

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. Alias namespaces must not collide on the shared 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:

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.

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.

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, 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.