stack/docs-mintlify/guides/integrations/tanstack-start/overview.mdx

---
title: TanStack Start
description: Add Hexclave to a TanStack Start app.
---

<Info>
  The `@hexclave/tanstack-start` package is currently alpha. Pin exact package versions before shipping production apps.
</Info>

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

<Steps>
  <Step title="Create or open a TanStack Start app">
    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.
  </Step>

  <Step title="Install Hexclave">
    Install the alpha TanStack Start package:

    ```bash title="Terminal"
    npm install @hexclave/tanstack-start
    ```
  </Step>

  <Step title="Create Hexclave keys">
    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=<your-project-id>
    HEXCLAVE_SECRET_SERVER_KEY=<your-secret-server-key>
    ```

    Keep `HEXCLAVE_SECRET_SERVER_KEY` server-only. Do not expose it to client code.
  </Step>

  <Step title="Create a Stack client app">
    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",
    });
    ```
  </Step>

  <Step title="Wrap the root route">
    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 (
        <HexclaveProvider app={hexclaveClientApp}>
          <HexclaveTheme>
            <Outlet />
          </HexclaveTheme>
        </HexclaveProvider>
      );
    }

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

  <Step title="Add the auth handler route">
    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 <HexclaveHandler fullPage location={pathname} />;
    }
    ```
  </Step>

  <Step title="Use auth in routes">
    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 <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:

    ```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 <div>Welcome, {user.primaryEmail}</div>;
    }
    ```
  </Step>
</Steps>

## 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).