TanStack Start - Hexclave Documentation

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

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 Hexclave

Install the alpha TanStack Start package:

Terminal

npm install @hexclave/tanstack-start

Create Hexclave keys

In the Hexclave 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 { HexclaveClientApp } from "@hexclave/tanstack-start";

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

Wrap the root route

Add HexclaveProvider and HexclaveTheme around your route outlet:

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 (
    <HexclaveProvider app={hexclaveClientApp}>
      <HexclaveTheme>
        <Outlet />
      </HexclaveTheme>
    </HexclaveProvider>
  );
}

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 Hexclave’s built-in pages:

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 <HexclaveHandler fullPage location={pathname} />;
}

Use auth in routes

Use Stack hooks from inside components rendered under the provider:

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 <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 "@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 <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 HexclaveClientApp.
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.

​Setup

​Notes

Setup

Notes