Getting Started with TanStack Start and Convex (2026 Guide)

This is the first article in our series on building a modern SaaS application with TanStack Start and Convex. TanStack Start is now at v1 Release Candidate, feature-complete with a stable API, and the tooling has changed significantly since the original 2025 version of this guide. By the end of this article you’ll have a running full-stack React app with SSR, file-based routing, and a realtime Convex backend.

What is TanStack Start?

TanStack Start is a full-stack React framework built on top of TanStack Router. It comes from the TanStack team (the same people behind TanStack Query, Router, Table, and other widely-used libraries). Key features:

• File-based routing: similar to Next.js or Remix, routes map to files in src/routes/.
• Server-side rendering (SSR) with client-side hydration.
• Integrated data fetching via TanStack Query hooks.
• Vite tooling (or Rsbuild 2 as an alternative) for fast dev and builds.
• Nitro-powered server output: deploy to any Node.js host, serverless platform, or VPS.

TanStack Start reached v1.0 Release Candidate in September 2025 and ships 1.x npm versions. The API is considered stable. If you want to see how TanStack Start compares to Next.js and Astro, we have a dedicated comparison.

What is Convex?

Convex is a realtime backend-as-a-service platform. It handles your database, serverless functions, and client sync so you can focus on frontend code. You can also build a real-time app with Convex using other frameworks.

Convex integrates with TanStack Start via the @convex-dev/react-query package, which lets you fetch and mutate data using standard TanStack Query hooks.

Prerequisites

Before you start, make sure you have:

No Docker, no VPS, no DNS needed for this tutorial. Everything runs locally.

Installation: scaffold with Convex

The fastest way to get started is the Convex template, which scaffolds a project with TanStack Start and Convex pre-wired:

npm create convex@latest -- -t tanstack-start my-saas-app
cd my-saas-app

npx create-start-app@latest
cd my-app
npm install convex @convex-dev/react-query @tanstack/react-router-with-query @tanstack/react-query

Verify the scaffold worked:

cat package.json | grep -E "tanstack|convex"

You should see @tanstack/react-start, @tanstack/react-router, @tanstack/react-query, convex, and @convex-dev/react-query in the output.

Failure mode: If npm create convex fails, check your Node version (node -v) and npm registry connectivity (npm ping).

Starting the development environment

Run the dev server:

npm run dev

Under the hood, this executes convex dev --start 'vite dev' — the Convex CLI drives Vite directly. On first run, Convex will prompt you to name your project and bootstrap a local backend:

? Choose a name: my-saas-app
✔ Downloaded Convex backend binary
✔ Started running a deployment locally at http://127.0.0.1:3210
    name as CONVEX_DEPLOYMENT to .env.local
    URL as VITE_CONVEX_URL to .env.local

  ➜ Local:    http://localhost:3000/
✔ Convex functions ready! (839.54ms)

cat .env.local | grep VITE_CONVEX_URL

What’s happening:

• Convex initialization: convex dev sets up a local backend, saves VITE_CONVEX_URL and CONVEX_DEPLOYMENT to .env.local. These connect your frontend to the Convex backend.
• Vite dev server: Your app runs at http://localhost:3000.
• Convex dashboard: Run npx convex dashboard to open the web UI for managing data, viewing logs, and testing functions.

Tip: Run npx convex login to link your local deployment to a Convex account for cloud syncing and deployment.

Failure modes:

• Missing VITE_CONVEX_URL: If the frontend can’t connect, restart npm run dev after the first convex dev bootstraps the env file.
• Port 3000 in use: Vite auto-picks another port (check terminal output), or set server.port in vite.config.ts.

Understanding the project structure

The scaffold creates this layout (note: src/, not app/):

.
├── src/
│   ├── routes/               # Page routes
│   │   ├── __root.tsx        # Root layout (HTML structure, global providers)
│   │   └── index.tsx         # Homepage component ('/')
│   ├── router.tsx            # Router setup (integrates Convex + Query)
│   ├── routeTree.gen.ts      # Auto-generated route tree
│   ├── start.ts              # App entry point (replaces old client.tsx + ssr.tsx)
│   └── styles/
│       └── app.css           # Global styles
├── convex/                   # Backend logic
│   ├── schema.ts             # Database schema (defines tables)
│   ├── _generated/           # Auto-generated types and API
│   └── ...                   # Your queries and mutations
├── public/                   # Static assets
├── .env.local                # Environment variables (VITE_CONVEX_URL)
├── vite.config.ts            # Vite configuration
├── convex.config.ts          # Convex config
├── package.json
└── tsconfig.json

Key files:

• src/router.tsx — creates the TanStack Router instance and wires up Convex + Query client. This is the integration point.
• src/routes/__root.tsx — defines the root layout (<html>, <head>, <body>) and renders <Outlet /> for child routes.
• src/routes/index.tsx — the homepage, uses createFileRoute('/').
• src/start.ts — the single entry point that replaces the old client.tsx + ssr.tsx.
• convex/schema.ts — defines your database tables. See the Convex schema docs.
• .env.local — stores VITE_CONVEX_URL. Never commit this file to Git.

How the router and Convex client wire together

The integration happens in src/router.tsx. Here’s the current template code:

// src/router.tsx
import { createRouter } from '@tanstack/react-router'
import { QueryClient } from '@tanstack/react-query'
import { routerWithQueryClient } from '@tanstack/react-router-with-query'
import { ConvexQueryClient } from '@convex-dev/react-query'
import { ConvexProvider } from 'convex/react'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  const CONVEX_URL = (import.meta as any).env.VITE_CONVEX_URL!
  if (!CONVEX_URL) console.error('missing envar VITE_CONVEX_URL')

  const convexQueryClient = new ConvexQueryClient(CONVEX_URL)
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        queryKeyHashFn: convexQueryClient.hashFn(),
        queryFn: convexQueryClient.queryFn(),
        gcTime: 5000,
      },
    },
  })
  convexQueryClient.connect(queryClient)

  const router = routerWithQueryClient(
    createRouter({
      routeTree,
      defaultPreload: 'intent',
      context: { queryClient },
      scrollRestoration: true,
      defaultPreloadStaleTime: 0,
      Wrap: ({ children }) => (
        <ConvexProvider client={convexQueryClient.convexClient}>
          {children}
        </ConvexProvider>
      ),
    }),
    queryClient,
  )
  return router
}

What’s happening:

1. ConvexQueryClient is constructed from VITE_CONVEX_URL — it bridges Convex functions with TanStack Query.
2. QueryClient is configured with Convex’s hashFn and queryFn so queries route through Convex automatically.
3. routerWithQueryClient from @tanstack/react-router-with-query connects the router and query client for SSR-aware data fetching.
4. ConvexProvider wraps the app via the Wrap prop, making the Convex client available to all components.
5. defaultPreloadStaleTime: 0 lets React Query own caching — this prevents double-fetches and stale data when using routerWithQueryClient.

Basic routing with TanStack Router

TanStack Start uses file-based routing via TanStack Router. Two files define the routing foundation:

src/routes/index.tsx — the homepage:

// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

function Home() {
  return (
    <div>
      <h1>Welcome to My SaaS App</h1>
      <p>Edit this page in <code>src/routes/index.tsx</code></p>
    </div>
  )
}

src/routes/__root.tsx — the root layout:

// src/routes/__root.tsx
import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from '@tanstack/react-router'
import type { QueryClient } from '@tanstack/react-query'

interface MyRouterContext {
  queryClient: QueryClient
}

export const Route = createRootRouteWithContext<MyRouterContext>()({
  component: RootComponent,
})

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  )
}

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}

Key points:

• createFileRoute('/') maps a file to a URL path.
• createRootRouteWithContext sets up the root layout with typed context (the queryClient from the router).
• HeadContent (replaces the old Meta) injects metadata into <head>.
• Scripts injects JavaScript bundles at the end of <body>.
• Outlet renders the current route’s component.

Adding a header and footer

Let’s add a header with navigation and a footer to src/routes/__root.tsx. This gives every page consistent branding:

// src/routes/__root.tsx
import {
  createRootRouteWithContext,
  HeadContent,
  Link,
  Outlet,
  Scripts,
} from '@tanstack/react-router'
import type { QueryClient } from '@tanstack/react-query'

interface MyRouterContext {
  queryClient: QueryClient
}

export const Route = createRootRouteWithContext<MyRouterContext>()({
  notFoundComponent: () => (
    <div style={{ textAlign: 'center', padding: '2rem' }}>
      <h1>404 - Page Not Found</h1>
      <Link to="/">Go Home</Link>
    </div>
  ),
  component: RootComponent,
})

function RootComponent() {
  return (
    <RootDocument>
      <header
        style={{
          padding: '1rem',
          borderBottom: '1px solid #eee',
          background: '#f8f9fa',
          position: 'sticky',
          top: 0,
          zIndex: 10,
        }}
        role="banner"
      >
        <nav aria-label="Main navigation">
          <Link
            to="/"
            style={{
              marginRight: '1rem',
              fontWeight: 'bold',
              color: '#333',
              textDecoration: 'none',
            }}
            aria-label="Home page"
          >
            My SaaS App
          </Link>
        </nav>
      </header>
      <main style={{ padding: '1rem', minHeight: '80vh' }} role="main">
        <Outlet />
      </main>
      <footer
        style={{
          padding: '1rem',
          borderTop: '1px solid #eee',
          textAlign: 'center',
          background: '#f8f9fa',
        }}
        role="contentinfo"
      >
        <p>&copy; {new Date().getFullYear()} My SaaS App. All rights reserved.</p>
      </footer>
    </RootDocument>
  )
}

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}

What changed from the 2025 version:

• Meta replaced by HeadContent (imported from @tanstack/react-router, not @tanstack/start).
• ScrollRestoration removed — handled by scrollRestoration: true in the router config.
• notFoundComponent added to fix the 404 warning.
• The MyRouterContext interface is simpler — the Convex client is wrapped via ConvexProvider in the router’s Wrap prop, so it doesn’t need to be in the context type.

Failure mode: If HeadContent import fails, you’re importing from @tanstack/start instead of @tanstack/react-router. Update the import.

Note on styling: This example uses inline styles for simplicity. The Convex template now ships with Tailwind v4, which you can use instead. Later articles in this series will introduce Radix UI components.

Verify your setup (build and smoke test)

Run a production build to catch type errors and confirm everything compiles:

npm run build

This runs npm run typecheck && vite build and outputs to .output/server/index.mjs (Nitro format). Then test the production server:

npm run start

Open the URL shown in the terminal. The app should render identically to dev mode.

Also verify the Convex backend:

npx convex dashboard

This opens the Convex dashboard in your browser. You should see your project listed with its functions.

Failure mode: If npm run build fails with TypeScript errors, run npm run typecheck first to isolate them. If you get OOM errors on a small VPS, increase Node memory: NODE_OPTIONS=--max-old-space-size=4096 npm run build.

Convex pricing and deployment notes

Convex has a generous free tier that’s enough for prototyping and early development:

Deployment architecture: Convex is a managed cloud backend — your Convex functions and database run in Convex’s cloud. The TanStack Start frontend can deploy to any Node.js host or Nitro-compatible platform. If you want to deploy your TanStack Start app on your own VPS, Dokploy is a solid option on something like Hetzner Cloud.

For deploying the Convex side to production, see our guide on how to deploy a Convex app to production. If you prefer keeping everything on your own infrastructure, you can look into self-hosting Convex — we also have benchmarks comparing Convex self-hosted vs cloud free tier performance.

Troubleshooting common issues

plugins: [
  tsConfigPaths({ projects: ['./tsconfig.json'] }),
  tanstackStart(),   // first
  viteReact(),       // after tanstackStart
],

What’s next in this series

Now that the foundation is in place, the next article will cover writing your first Convex query and mutation — using the tasks example from the quickstart. You’ll learn how to define a schema, write server functions, and fetch data with useSuspenseQuery and convexQuery from @convex-dev/react-query.

The series will also cover Clerk authentication, Radix UI components, and Polar.sh payments.