Project Structure

Use src/routes for pages and layouts, src/components for shared UI, and src/api for HTTP endpoints. Business behavior stays in services and repositories, so changing a page does not move authorization into the browser.

Choose an edit point

Navigate native routes

__root.tsx renders the document and shared providers. A folder's route.tsx wraps its children; index.tsx renders its base URL. The underscore in _marketing groups public pages without adding a URL segment. $slug matches one segment and $ matches the remaining path. TanStack Router generates src/routeTree.gen.ts; edit route files rather than the generated tree.

The authenticated dashboard verifies the Supabase user through src/lib/dashboard.server.ts before rendering its shared shell. The public /demo/dashboard routes reuse that shell with disclosed sample data. Account, Billing, Organizations and Projects read real signed-in state; labelled sample pages keep their existing nonpersistent behavior.

Keep server and browser code separate

src/routes/api/$.ts forwards the canonical /api/* surface to Hono. Add business endpoints to the existing Hono modules, then call them through a React Query hook. The normal write path is:

component → hook → Hono route → service/policy → repository/provider.

Route components can run during server rendering and in the browser. Keep privileged work in server-function handlers or modules marked @tanstack/react-start/server-only. Narrow server functions provide route bootstrap, language preference, feedback and content rendering; Hono remains the business API.

src/lib/docs.server.tsx checks access before rendering selected MDX through native RSC. Raw Markdown repeats the access check. Keep MDX collections and private bodies on that server boundary when adding content components.

src/router.tsx creates a fresh QueryClient per server request and installs the single SSR hydration provider. src/start.ts handles native request middleware, session refresh and server-function CSRF. The existing Supabase server factory reads and writes cookies in that request scope.

Build and configure

vite.config.ts connects Start, React, Fumadocs, Tailwind and Nitro. bun run build compiles the app and checks TypeScript; the Node output starts at .output/server/index.mjs. Dependencies and both E2E roots use the root bun.lock.

Keep browser settings under the existing NEXT_PUBLIC_* names and read them through explicit import.meta.env entries. Vite exposes that prefix only. Database URLs, provider secrets and admin clients remain server-only.

What's next