TanStack Start - Stack Auth Documentation

The @stackframe/tanstack-start package is currently alpha. Pin exact package versions before shipping production apps.

TanStack Start is a full-stack React framework built on TanStack Router and Vite. Stack Auth’s TanStack Start package provides the same auth components and hooks as the React SDK, with cookie handling wired for TanStack Start.

Setup

Create or open a TanStack Start app

If you do not have a TanStack Start app yet, create one with the TanStack CLI:

Terminal

npx @tanstack/cli@latest create

TanStack also publishes official examples if you prefer to start from a working project.

Install Stack Auth

Install the alpha TanStack Start package:

Terminal

npm install @stackframe/tanstack-start

Create Stack Auth keys

In the Stack Auth dashboard, create a project and add these variables to your TanStack Start environment:

.env

VITE_STACK_PROJECT_ID=<your-project-id>
STACK_SECRET_SERVER_KEY=<your-secret-server-key>

Keep STACK_SECRET_SERVER_KEY server-only. Do not expose it to client code.

Create a Stack client app

Create a Stack client app with cookie storage:

src/stack/client.ts

import { StackClientApp } from "@stackframe/tanstack-start";

export const stackClientApp = new StackClientApp({
  projectId: import.meta.env.VITE_STACK_PROJECT_ID,
  tokenStore: "cookie",
  redirectMethod: "window",
});

Wrap the root route

Add StackProvider and StackTheme around your route outlet:

src/routes/__root.tsx

import { StackProvider, StackTheme } from "@stackframe/tanstack-start";
import { createRootRoute, HeadContent, Outlet, Scripts } from "@tanstack/react-router";
import { stackClientApp } from "../stack/client";

export const Route = createRootRoute({
  component: RootComponent,
  shellComponent: RootDocument,
});

function RootComponent() {
  return (
    <StackProvider app={stackClientApp}>
      <StackTheme>
        <Outlet />
      </StackTheme>
    </StackProvider>
  );
}

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

Add the auth handler route

Create a splat route at /handler/* for Stack Auth’s built-in pages:

src/routes/handler/$.tsx

import { StackHandler } from "@stackframe/tanstack-start";
import { createFileRoute, useLocation } from "@tanstack/react-router";

export const Route = createFileRoute("/handler/$")({
  ssr: false,
  component: HandlerPage,
});

function HandlerPage() {
  const { pathname } = useLocation();
  return <StackHandler fullPage location={pathname} />;
}

Use auth in routes

Use Stack hooks from inside components rendered under the provider:

src/routes/index.tsx

import { useUser } from "@stackframe/tanstack-start";
import { createFileRoute, Link } from "@tanstack/react-router";

export const Route = createFileRoute("/")({
  component: HomePage,
});

function HomePage() {
  const user = useUser();

  if (!user) {
    return <Link to="/handler/sign-in">Sign in</Link>;
  }

  return <div>Signed in as {user.primaryEmail}</div>;
}

Routes that use browser redirects should render on the client:

src/routes/protected.tsx

import { useUser } from "@stackframe/tanstack-start";
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/protected")({
  ssr: false,
  component: ProtectedPage,
});

function ProtectedPage() {
  const user = useUser({ or: "redirect" });
  return <div>Welcome, {user.primaryEmail}</div>;
}

Notes

The handler route must stay under the same origin as your app when using tokenStore: "cookie".
Render the handler route on the client (ssr: false) because built-in auth pages read browser location state.
Render routes that rely on useUser({ or: "redirect" }) on the client (ssr: false) when using redirectMethod: "window".
Use redirectMethod: "window" unless you explicitly wire a TanStack Router navigation adapter.
If you change auth routes, configure the matching urls on StackClientApp.
For server-only logic, use TanStack Start server functions and keep STACK_SECRET_SERVER_KEY out of client modules.

For TanStack Start framework details, see the TanStack Start quick start and server functions guide.

Documentation Index

​Setup

​Notes

Setup

Notes