TanStack Start

Full-stack React framework powered by Vite, file-based routing via TanStack Router, and server functions via Nitro — a top priority addition to Fusion Stack.

Overview

When you select TanStack Start as your frontend, Fusion Stack scaffolds a full-stack React application using TanStack Start v1 with Vinxi as the build tool, file-based routing, and Tailwind CSS v4.

TanStack Start is full-stack by nature — it includes its own server runtime (Nitro) for server functions and API routes, so no separate backend process is required. You can still pair it with Convex (cloud backend) or Hono (separate API server on port :3001).

Scaffolded Structure

app/
  routes/
    __root.tsx          # Root document — html, head, body, Outlet, Scripts
    index.tsx           # Home page route (createFileRoute("/"))
  client.tsx            # Browser entry — hydrateRoot + StartClient
  router.tsx            # Router factory — createRouter + routeTree
  ssr.tsx               # Server entry — createStartHandler
  globals.css           # @import "tailwindcss";
app.config.ts           # Vinxi/TanStack Start config + Tailwind Vite plugin
tsconfig.json           # bundler moduleResolution, @/* → ./* alias
package.json
.gitignore              # includes .vinxi/ and app/routeTree.gen.ts

Note: The app/routeTree.gen.ts file is auto-generated by TanStack Router the first time you run vinxi dev. It is listed in .gitignore and should not be committed.

Scripts

Script	Command
`dev`	`vinxi dev`
`build`	`vinxi build`
`start`	`vinxi start`

When a Hono backend is also selected, dev becomes:

concurrently "vinxi dev" "tsx watch src/server/index.ts"

Use dev:client or dev:server to run them individually.

File-Based Routing

Routes live in app/routes/ and are automatically registered by the TanStack Router Vite plugin. File names map directly to URL paths:

File	URL
`app/routes/index.tsx`	`/`
`app/routes/about.tsx`	`/about`
`app/routes/blog/$id.tsx`	`/blog/:id`
`app/routes/__root.tsx`	Root layout (wraps all routes)

To add a new route:

// app/routes/about.tsx
import { createFileRoute } from "@tanstack/react-router"

export const Route = createFileRoute("/about")({
  component: AboutPage,
})

function AboutPage() {
  return <h1>About</h1>
}

Server Functions & API Routes

TanStack Start exposes two patterns for server-side logic:

Server Functions

import { createServerFn } from "@tanstack/start"

const getData = createServerFn().handler(async () => {
  // Runs on the server only — safe to use DB, secrets, etc.
  return { message: "Hello from the server" }
})

// Call it from any component or route loader:
const data = await getData()

API Routes

// app/routes/api/hello.ts
import { createAPIFileRoute } from "@tanstack/start/api"

export const APIRoute = createAPIFileRoute("/api/hello")({
  GET: () => new Response(JSON.stringify({ message: "Hello" })),
})

Path Alias

The @ alias maps to the project root (./*), not ./src/:

import { cn } from "@/app/lib/utils"     // app/lib/utils.ts
import { authClient } from "@/app/lib/auth-client"

Tailwind CSS v4

Tailwind is loaded via the @tailwindcss/vite plugin in app.config.ts. Styles are imported directly in app/globals.css:

@import "tailwindcss";

Backend Options

TanStack Start has three backend modes:

Backend	How it works
TanStack Start (built-in)	`createAPIFileRoute` + `createServerFn` — native, no separate process
Hono	Separate Node.js server on `:3001` — `pnpm dev` runs both via `concurrently`
Convex	Cloud backend — `npx convex dev` syncs schema and functions
None	Frontend-only

The built-in backend is the natural choice for TanStack Start projects — it uses the same Nitro server that's already running your app.

Auth Integration

Fusion Stack scaffolds the correct auth setup automatically based on your selection:

Auth	Package	Integration
Clerk	`@clerk/tanstack-start`	`ClerkProvider` wraps `__root.tsx`; `getServerAuth()` helper in `app/lib/auth.ts`
Better Auth	`better-auth`	API route at `/api/auth/$` (all methods); client in `app/lib/auth-client.ts`
WorkOS	`@workos-inc/node`	OAuth flow via `/auth/sign-in` and `/auth/callback` API routes

Environment Variables

TanStack Start uses the VITE_ prefix for public (browser-accessible) env vars, since it's Vite-based:

# Clerk
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# WorkOS
WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...

# Better Auth
AUTH_SECRET=...

# Database (if selected)
DATABASE_URL=...

Local URLs

Service	URL
TanStack Start app	`http://localhost:3000`
Hono API (if selected)	`http://localhost:3001`
Convex dashboard (if selected)	`https://dashboard.convex.dev`

On this page