---
title: TanStack Start
description: Add Hexclave to a TanStack Start app.
---
The `@hexclave/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. Hexclave's TanStack Start package provides the same auth components and hooks as the React SDK, with cookie handling wired for TanStack Start.
## Setup
If you do not have a TanStack Start app yet, create one with the TanStack CLI:
```bash title="Terminal"
npx @tanstack/cli@latest create
```
TanStack also publishes official examples if you prefer to start from a working project.
Install the alpha TanStack Start package:
```bash title="Terminal"
npm install @hexclave/tanstack-start
```
In the [Hexclave dashboard](https://app.hexclave.com/projects), create a project and add these variables to your TanStack Start environment:
```bash title=".env"
VITE_HEXCLAVE_PROJECT_ID=
HEXCLAVE_SECRET_SERVER_KEY=
```
Keep `HEXCLAVE_SECRET_SERVER_KEY` server-only. Do not expose it to client code.
Create a Stack client app with cookie storage:
```ts title="src/stack/client.ts"
import { HexclaveClientApp } from "@hexclave/tanstack-start";
export const hexclaveClientApp = new HexclaveClientApp({
projectId: import.meta.env.VITE_HEXCLAVE_PROJECT_ID,
tokenStore: "cookie",
redirectMethod: "window",
});
```
Add `HexclaveProvider` and `HexclaveTheme` around your route outlet:
```tsx title="src/routes/__root.tsx"
import { HexclaveProvider, HexclaveTheme } from "@hexclave/tanstack-start";
import { createRootRoute, HeadContent, Outlet, Scripts } from "@tanstack/react-router";
import { hexclaveClientApp } from "../stack/client";
export const Route = createRootRoute({
component: RootComponent,
shellComponent: RootDocument,
});
function RootComponent() {
return (
);
}
function RootDocument({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
Create a splat route at `/handler/*` for Hexclave's built-in pages:
```tsx title="src/routes/handler/$.tsx"
import { HexclaveHandler } from "@hexclave/tanstack-start";
import { createFileRoute, useLocation } from "@tanstack/react-router";
export const Route = createFileRoute("/handler/$")({
ssr: false,
component: HandlerPage,
});
function HandlerPage() {
const { pathname } = useLocation();
return ;
}
```
Use Stack hooks from inside components rendered under the provider:
```tsx title="src/routes/index.tsx"
import { useUser } from "@hexclave/tanstack-start";
import { createFileRoute, Link } from "@tanstack/react-router";
export const Route = createFileRoute("/")({
component: HomePage,
});
function HomePage() {
const user = useUser();
if (!user) {
return Sign in;
}
return
Signed in as {user.primaryEmail}
;
}
```
Routes that use browser redirects should render on the client:
```tsx title="src/routes/protected.tsx"
import { useUser } from "@hexclave/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
Welcome, {user.primaryEmail}
;
}
```
## 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 `HexclaveClientApp`.
- For server-only logic, use TanStack Start server functions and keep `HEXCLAVE_SECRET_SERVER_KEY` out of client modules.
For TanStack Start framework details, see the [TanStack Start quick start](https://tanstack.com/start/latest/docs/framework/react/quick-start) and [server functions guide](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions).