TanStack Start And Rust Migration

​

Runtime Shape

​

Rendering And Cache Policy

​

Cloudflare Preview Deployment

• apps/backend/wrangler.jsonc for the Rust Worker bundle.
• apps/tanstack-web/wrangler.jsonc for the TanStack Start Worker.
• @cloudflare/vite-plugin in apps/tanstack-web/vite.config.ts, registered before tanstackStart().
• root wrangler tooling plus bun check:cloudflare to validate both Worker configs without contacting Cloudflare.

bun check:cloudflare

• apps/backend/.dev.vars
• apps/tanstack-web/.dev.vars

rustup target add wasm32-unknown-unknown
cargo install worker-build --locked
bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
bun wrangler secret put TUTURUUU_APP_COORDINATION_SECRET --config apps/backend/wrangler.jsonc
bun wrangler secret put SUPABASE_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put SUPABASE_SERVICE_ROLE_KEY --config apps/backend/wrangler.jsonc
bun wrangler secret put CRON_SECRET --config apps/backend/wrangler.jsonc
bun wrangler secret put DISCORD_APP_DEPLOYMENT_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put AURORA_EXTERNAL_URL --config apps/backend/wrangler.jsonc
bun wrangler secret put AURORA_EXTERNAL_WSID --config apps/backend/wrangler.jsonc
bun wrangler deploy --config apps/backend/wrangler.jsonc

curl -fsS https://<backend-worker-origin>/healthz
curl -fsS https://<backend-worker-origin>/readyz
curl -fsS \
  -H "Authorization: Bearer ${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
  https://<backend-worker-origin>/api/migration/status

bun wrangler secret put BACKEND_PUBLIC_ORIGIN --config apps/tanstack-web/wrangler.jsonc
bun wrangler secret put BACKEND_INTERNAL_TOKEN --config apps/tanstack-web/wrangler.jsonc

bun wrangler versions secret put BACKEND_INTERNAL_TOKEN --config apps/backend/wrangler.jsonc
bun wrangler versions secret put TUTURUUU_APP_COORDINATION_SECRET --config apps/backend/wrangler.jsonc
bun wrangler versions secret put SUPABASE_URL --config apps/backend/wrangler.jsonc
bun wrangler versions secret put SUPABASE_SERVICE_ROLE_KEY --config apps/backend/wrangler.jsonc
bun wrangler versions secret put CRON_SECRET --config apps/backend/wrangler.jsonc
bun wrangler versions secret put DISCORD_APP_DEPLOYMENT_URL --config apps/backend/wrangler.jsonc
bun wrangler versions secret put AURORA_EXTERNAL_URL --config apps/backend/wrangler.jsonc
bun wrangler versions secret put AURORA_EXTERNAL_WSID --config apps/backend/wrangler.jsonc
bun wrangler versions deploy --config apps/backend/wrangler.jsonc

bun wrangler versions secret put BACKEND_PUBLIC_ORIGIN --config apps/tanstack-web/wrangler.jsonc
bun wrangler versions secret put BACKEND_INTERNAL_TOKEN --config apps/tanstack-web/wrangler.jsonc
bun wrangler versions deploy --config apps/tanstack-web/wrangler.jsonc

bun --cwd apps/tanstack-web run cf-typegen
bun --cwd apps/tanstack-web run deploy:cloudflare

bun wrangler dev --config apps/backend/wrangler.jsonc
bun --cwd apps/tanstack-web run preview:cloudflare

BACKEND_INTERNAL_TOKEN="${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
BACKEND_WORKER_ORIGIN=http://localhost:8780 \
TANSTACK_WEB_WORKER_ORIGIN=http://localhost:8784 \
bun smoke:cloudflare \
  --output tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json

bun migration:tanstack:gates -- \
  --allow-legacy \
  --skip-benchmark \
  --skip-e2e \
  --cloudflare-smoke-report tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json

bun wrangler deployments list --config apps/backend/wrangler.jsonc
bun wrangler deployments status --config apps/backend/wrangler.jsonc
bun wrangler rollback <VERSION_ID> --config apps/backend/wrangler.jsonc

bun wrangler deployments list --config apps/tanstack-web/wrangler.jsonc
bun wrangler deployments status --config apps/tanstack-web/wrangler.jsonc
bun wrangler rollback <VERSION_ID> --config apps/tanstack-web/wrangler.jsonc

• Runtime service binding smoke is pending. The config and internal client use the BACKEND binding, but deployed smoke still needs to prove the binding path in Cloudflare preview before production host routing.
• Production host routing is pending full route manifest completion, Docker compare-mode E2E evidence, benchmark evidence, and bun migration:tanstack:gates.
• Preview Workers should not become the owner for private workspace/admin APIs until each route has backend tests, OpenAPI coverage, an internal-api facade, and migration gate evidence.

​

Route Ownership Manifest

​

Rust GET-handler migration wave

​

Worker-incompatible routes (native-backend or Next.js only)

• Native-backend portable (deferred, needs secrets wired): the scheduler /api/cron/* jobs that just “call an external API + write Supabase” — finance/exchange-rates, inventory/polar-product-sync, payment/{orders,products,subscriptions}, ai/sync-models, tasks/generate-embeddings, calendar/{provider-sync,smart-schedule}, process-{post-email-queue,topic-announcement-queue,notification-batches}, and hive/simulate. These ARE portable to the native Rust container target (--features native, which can do outbound HTTP and reach external DBs) once each job’s provider secret/connection is added to BackendConfig + wrangler.jsonc secrets. They are not portable to the wasm Worker build. Until the secrets are wired they stay on Next.js (Bearer CRON_SECRET).
• Host/infra-coupled (stay where the runner lives): the cron-runner monitoring surface — monitoring/cron/{control,run,runner-recovery,executions}, plus cron/infrastructure/{docker-recovery-alerts,sample-resources} — reads a filesystem archive / controls the deployment host (Docker control), and cron/infrastructure/sync-trust-cache needs Redis. These belong with whatever orchestrates the runner, not a stateless handler.
• Transport that can’t be a single handler: /api/trpc/[trpc] is a catch-all that dispatches the entire tRPC procedure router (appRouter). The transport stays on Next.js; its data access migrates incrementally as individual procedures move behind packages/internal-api / the Rust backend.

• 151 pages
• 58 layouts
• 587 route handler artifacts
• 8 cron handlers
• 800 total tracked route artifacts
• 215 migrated artifacts, 228 terminal artifacts, and 572 remaining legacy-owned artifacts in the checked manifest

bun migration:tanstack:manifest

bun migration:tanstack:routes

bun migration:tanstack:check

bun migration:tanstack:cutover-check

bun migration:tanstack:gates -- \
  --e2e-report tmp/e2e/web-migration/compare-report.json \
  --benchmark-report tmp/benchmarks/web-migration/<timestamp>/report.json \
  --cloudflare-smoke-report tmp/benchmarks/web-migration/<timestamp>/cloudflare-smoke.json \
  --output tmp/benchmarks/web-migration/<timestamp>/cutover-gates.json

GET /api/migration/progress

​

Frontend Runtime Adapters

​

Data And API Rules

• TanStack loaders and server functions may act as a BFF layer for SSR, cookies, headers, and query hydration.
• Product data reads/writes move to Rust-owned endpoints in apps/backend.
• Browser/shared UI code calls packages/internal-api helpers, not scattered raw API paths.
• Protected data stays behind server-owned private/admin access. Do not expose private Supabase or protected workspace reads directly to browser code.
• Use TanStack Query for client fetching and mutation. Do not fetch data in useEffect.
• bun check runs node scripts/check-tanstack-api-access.js to enforce that apps/tanstack-web/src does not call relative protected /api, /internal, or /trpc paths directly and does not import or create Supabase clients. Run the focused command when reviewing a frontend port before the full repo check.

​

Backend Crate Structure And The 700-LOC Ceiling

• src/lib.rs (~680 LOC) is now just the module registry (mod <handler>;), the public types, and pub(crate) use re-exports.
• src/dispatch/ holds handle_backend_request plus one dispatch_chunk_NN.rs per route-table chunk. New route arms append to a dispatch_chunk_NN.rs; when a chunk approaches 700 LOC, add a fresh chunk_NN.rs and wire it into dispatch/mod.rs. Each chunk does use crate::*; to reach crate-root helpers/types.
• Cohesive helper families live in named submodules, each under 700 LOC: types.rs, response.rs, runtime.rs, migration.rs, legacy_routes.rs, static_routes.rs, route_predicates.rs, config_env.rs, constants.rs, native.rs, worker_runtime.rs. Each is re-exported from lib.rs with pub(crate) use <mod>::*; so existing call sites resolve unchanged.
• The unit-test suite lives in src/tests.rs (mod tests;), split by area so no test file crosses the ceiling.

​

No New Debt While The Switch Is Pending

• New or changed apps/web API route (any method). If apps/backend already owns that path, port the same behavior change into the Rust handler in the same PR (match status codes, body shape, cache headers; migrate GET first and return None for un-ported methods so they fall through). If it is not owned yet, register/refresh the route in apps/tanstack-web/migration/route-overrides.json and regenerate with bun migration:tanstack:manifest, so the new surface is tracked as backlog instead of invisible debt. Verify ownership with the runtime coverage probe in apps/backend/AGENTS.md (migrated method = COVER, un-ported = FRESH).
• New or changed dashboard page/route. Mirror the manifest registration so apps/tanstack-web tracking stays accurate, and route shared data access through packages/internal-api (consumed by both frontends) rather than app-local fetchers, so the eventual TanStack port is a move, not a rewrite.
• Shared data access. Prefer adding a packages/internal-api facade over a one-off apps/web fetcher; the facade is the seam both the Next.js and TanStack frontends call, and it forwards to the Rust backend server-side.
• Tracking, not blocking. You do not have to finish the Rust/TanStack port in every PR, but you must leave the manifest accurate. A route that is added to apps/web and not reflected in the manifest is the debt this migration exists to avoid. bun migration:tanstack:check and the backend coverage probe are the guards.

​

Security And Test Requirements

• a route-overrides.json entry with a non-empty evidence note that marks the legacy artifact as migrated or accepted-removal
• an OpenAPI path or schema update in apps/backend/api/openapi.yaml
• a Rust route dispatcher test covering the success case; full-route ownership also needs unsupported method behavior, while method-level ownership needs an assertion that still-legacy sibling methods are not claimed by Rust
• a packages/internal-api facade when the TanStack app or shared UI needs to call the endpoint

• Bind BACKEND_INTERNAL_TOKEN, BACKEND_PUBLIC_ORIGIN, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, CRON_SECRET, and DISCORD_APP_DEPLOYMENT_URL, plus AURORA_EXTERNAL_URL and AURORA_EXTERNAL_WSID, with wrangler secret put, wrangler versions secret put, or Cloudflare dashboard secret bindings. The TanStack Worker reaches the backend Worker through the BACKEND service binding; configure BACKEND_INTERNAL_URL only for non-binding HTTP fallback runs. Use secret put for first preview bootstrap only because it deploys a new active version immediately; use the versions command family for rotations and canaries.
• Bind TUTURUUU_APP_COORDINATION_SECRET on the backend Worker before testing contact/profile routes. The Rust verifier also accepts existing app-coordination fallback secret names for compatibility, but the dedicated secret name is the preferred Cloudflare binding.
• Keep local Worker secret values in ignored apps/backend/.dev.vars and apps/tanstack-web/.dev.vars files. Do not commit literal origins that are account-specific private targets, tokens, API keys, cookies, or session material.
• CMS_APP_URL and NEXT_PUBLIC_CMS_APP_URL are public origin allowlist inputs for the WebGL upload preflight. They may be supplied through Wrangler vars or local .dev.vars, but they are not backend tokens and must not be listed as required secrets.
• Keep private/admin data ownership server-side. If a migrated endpoint needs a Supabase service role or private schema access, the Rust backend owns that call path; the browser receives only the authorized response shape.
• Review CORS, cookie domain, SameSite, secure-cookie, and session-origin behavior before mapping a custom hostname. Preview workers.dev origins are different sites from tuturuuu.localhost and production tuturuuu.com, so cookie/session behavior must be proven with smoke or E2E evidence rather than assumed from Docker.
• Keep BACKEND_ENV=preview for Cloudflare preview. Development-only migration routes and local E2E bypasses must not be enabled by Worker deploys.
• Do not bypass the migration gate because a Worker smoke passed. Worker smoke proves deploy compatibility; cutover still requires manifest, Docker E2E, and benchmark evidence.

​

Docker And E2E

bun test:e2e:web:docker -- --frontend next

bun test:e2e:web:docker -- --frontend tanstack

bun test:e2e:web:docker -- --frontend compare

​

Benchmarks

bun benchmark:web-setups -- --setup compare --profile smoke

BACKEND_INTERNAL_TOKEN="${BACKEND_INTERNAL_TOKEN:?set BACKEND_INTERNAL_TOKEN}" \
bun benchmark:web-setups -- \
  --setup compare \
  --profile smoke \
  --next-origin https://<legacy-next-origin> \
  --tanstack-origin https://<tanstack-worker-origin> \
  --backend-origin https://<backend-worker-origin>

bun benchmark:web-setups -- --setup compare --profile full --require-all

{
  "metrics": {
    "backend": {
      "apiLatencyP50Ms": 80,
      "apiLatencyP95Ms": 120,
      "apiLatencyP99Ms": 180
    },
    "next": {
      "apiLatencyP50Ms": 75,
      "apiLatencyP95Ms": 110,
      "apiLatencyP99Ms": 170,
      "devReadyMs": 2200,
      "dockerBuildMs": 240000,
      "e2ePassRate": 1,
      "e2eWallMs": 90000,
      "firstRouteColdMs": 650,
      "imageSizeBytes": 1200000000,
      "jsOutputBytes": 850000,
      "productionCpuPercent": 4,
      "productionRssBytes": 640000000,
      "warmNavigationMs": 180
    },
    "tanstack": {
      "devReadyMs": 1800,
      "dockerBuildMs": 180000,
      "e2ePassRate": 1,
      "e2eWallMs": 84000,
      "firstRouteColdMs": 520,
      "imageSizeBytes": 760000000,
      "jsOutputBytes": 620000,
      "productionCpuPercent": 3,
      "productionRssBytes": 420000000,
      "warmNavigationMs": 140
    }
  },
  "acceptedRegressions": [
    {
      "metric": "first-route-cold-time",
      "note": "Approved while Cloudflare preview cache is cold."
    }
  ]
}

bun benchmark:web-setups -- \
  --setup compare \
  --profile full \
  --require-all \
  --evidence tmp/benchmarks/web-migration/evidence.json

• frontend route p95 must not regress more than 25%
• Cloudflare smoke evidence must include passing backend-health, backend-ready, backend-migration-status, backend-migration-status-missing-token, backend-migration-status-invalid-token, and tanstack-root probes
• cutover reports must include the full metric comparison contract: API p50/p95/p99, dev ready time, first-route cold time, warm navigation time, Docker build time, image size, JS output size, production RSS/CPU baseline, E2E wall time, and E2E pass rate, with numeric baseline, candidate, ratio, and threshold values for each required comparison
• full compare evidence must include complete matching frontend route coverage; unmatched Next-only or TanStack-only routes fail --require-all and cutover gate validation
• representative backend smoke routes must stay below the smoke ceiling
• strict runs fail when any required route is unreachable

​

Cutover Checklist

1. Every manifest route is migrated or accepted-removal.
2. bun migration:tanstack:cutover-check passes.
3. bun test:e2e:web:docker -- --frontend compare passes and has a compare evidence report.
4. bun benchmark:web-setups -- --setup compare --profile full --require-all passes or has approved exceptions. HTTPS origins must present a certificate trusted by the host; use the local development CA or NODE_EXTRA_CA_CERTS instead of disabling certificate verification.
5. bun smoke:cloudflare --output <path> passes against the preview Workers.
6. bun migration:tanstack:gates -- --e2e-report <path> --benchmark-report <path> --cloudflare-smoke-report <path> passes.
7. bun check:docker and bun check pass.
8. Legacy apps/web remains available as the rollback fixture until production monitoring shows the TanStack/Rust path is stable.