---
title: "Introducing the Auth0 SDK for TanStack Start"
description: "Meet the new Auth0 SDK for TanStack Start and learn how to use it to add authentication to your apps."
authors:
  - name: "Rengarajan R"
    url: "https://auth0.com/blog/authors/rengarajan-r/"
date: "Oct 13, 2026"
category: "Developers,Tutorial"
tags: ["sdk", "javascript", "tanstack"]
url: "https://auth0.com/blog/introducing-the-auth0-sdk-for-tanstack-start/"
---

# Introducing the Auth0 SDK for TanStack Start

TanStack Start has quickly become one of the most talked-about full-stack React frameworks, and until now, wiring up authentication meant hand-rolling OpenID Connect (OIDC) flows or [adapting an SDK that was never built for it](https://auth0.com/blog/everybody-thinks-login-is-easy). That changes with `@auth0/auth0-tanstack-start-react`, a new SDK purpose-built for TanStack Start's server functions, middleware, and file-based router. 

In this post, we will look at what the SDK gives you out of the box, and walk through adding login, logout, and a protected route to a TanStack Start app in a few minutes.

## Why a Dedicated SDK

TanStack Start is not Next.js or Remix. It has its own conventions for middleware (`createMiddleware`), server functions (`createServerFn`), and route context (`beforeLoad`). A generic Node OIDC client can get you logged in, but it will not give you typed router context, route guards that plug into `beforeLoad`, or session helpers that work inside TanStack Start's server functions. The new SDK was built against those primitives directly, so authentication state flows through the router the same way your loader data does.

## What You Get

The SDK ships a small, focused API surface:

- **Hooks:** `useAuth0`, `useUser`, `useOrg`, `useLogin`, `useLogout`, `useMfa`
- **Components:** `SignedIn`, `SignedOut`, `HasOrg`, `AuthReady`, `AuthLoading` - declarative conditional rendering based on auth state
- **Route guards:** `requireAuth` and `requireOrg` for use in a route's `beforeLoad`
- **Server middleware:** `requireAuthMiddleware`, `withApiAuth`, `withApiScopes`, `withApiOrg`, and claim-based guards like `withApiClaimIncludes`
- **Server helpers:** `getSession(auth0)`, `getAccessToken(auth0)`, `getTokenSet(auth0)`, `createFetcher(auth0)`

Auth routes (`/auth/login`, `/auth/callback`, `/auth/logout`, `/auth/profile`, `/auth/backchannel-logout`) are mounted automatically once the middleware is registered. There is no route handler file to write yourself.

## Setup Auth0 for TanStack Start Apps

Let's see how to set up Auth0 for your StanStack Start application.

### Install the Auth0 SDK for Tanstack Start

Execute the following command in your terminal where you have your Tanstack Start React app to install the Auth0 SDK:

```bash
npm install @auth0/auth0-tanstack-start-react
```

Peer dependencies are React 18 or 19, `@tanstack/react-router`, and `@tanstack/react-start` v1.

### Configure environment variables

Create an Auth0 application (Regular Web App in [Auth0 dashboard](https://manage.auth0.com/)) and set the following as environment variables:

```java
AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
AUTH0_CLIENT_SECRET=YOUR_AUTH0_APP_CLIENT_SECRET
AUTH0_SECRET=YOUR_LONG_RANDOM_SECRET_HERE
APP_BASE_URL=http://localhost:3000
```

Generate `AUTH0_SECRET` with `openssl rand -hex 32`, and set your app's callback URL to `http://localhost:3000/auth/callback`.

### Create the server-side Auth0 instance

Create a server side Auth0 instance to use Auth0 authentication in your TanStack app, as shown in the following code:

```js
// src/auth.server.ts
import { auth0Server } from '@auth0/auth0-tanstack-start-react/server';

export const auth0 = auth0Server();
```

### Register the middleware

Register the Auth0 specific middleware in your app to mount auth routes:

```js
// src/start.ts
import { createStart } from '@tanstack/react-start';
import { auth0Middleware } from '@auth0/auth0-tanstack-start-react/server/middleware';

export const startInstance = createStart(() => ({
  requestMiddleware: [auth0Middleware()],
}));
```

Import from `/server/middleware`, not the `/server` barrel, in `start.ts`. That file runs in both the client and server bundles, and pulling in the full `/server` module here will break the client build.

### Wire up router context and the provider

In the `router.tsx` file, include `auth0RouterContext` to access Auth0 router context across routes: 

```typescript
// src/router.tsx
import { createRouter as createTanStackRouter } from '@tanstack/react-router';
import { auth0RouterContext } from '@auth0/auth0-tanstack-start-react/client';
import type { Auth0RouterContext } from '@auth0/auth0-tanstack-start-react/types';
import { routeTree } from './routeTree.gen';

export interface RouterContext {
  auth0: Auth0RouterContext;
}

export function getRouter() {
  return createTanStackRouter({
    routeTree,
    context: { auth0: auth0RouterContext } satisfies RouterContext,
  });
}

declare module '@tanstack/react-router' {
  interface Register {
    router: ReturnType<typeof getRouter>;
  }
}
```

Next, update your root route file to wire up the Auth0 router context and wrap your application in the `Auth0Provider`. This ensures authentication state is properly initialized and available across all routes:

```js
// src/routes/__root.tsx
import { createRootRouteWithContext } from '@tanstack/react-router';
import { Auth0Provider, auth0BeforeLoad } from '@auth0/auth0-tanstack-start-react/client';
import type { RouterContext } from '../router';

export const Route = createRootRouteWithContext<RouterContext>()({
  beforeLoad: auth0BeforeLoad(),
  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Auth0Provider>{children}</Auth0Provider>
      </body>
    </html>
  );
}
```

### Add login and logout

Add login and logout support for your application as shown inn the following examples.

The following code snippet implements a login butto:

```js
// src/components/LoginButton.tsx
import { useLogin } from '@auth0/auth0-tanstack-start-react/client';

export function LoginButton() {
  const login = useLogin();
  return <button onClick={() => login('/dashboard')}>Log In</button>;
}
```

Here is the logout button implementation:

```js
// src/components/LogoutButton.tsx
import { useLogout } from '@auth0/auth0-tanstack-start-react/client';

export function LogoutButton() {
  const logout = useLogout();
  return <button onClick={() => logout()}>Log Out</button>;
}
```

`useLogin` and `useLogout` trigger a full browser navigation rather than a client-side router transition, since the auth routes they hit are handled on the server.

### Protect a route

Use `requireAuth` to protect a route in your app, as shown below:

```js
// src/routes/dashboard.tsx
import { createFileRoute } from '@tanstack/react-router';
import { requireAuth, useUser } from '@auth0/auth0-tanstack-start-react/client';

export const Route = createFileRoute('/dashboard')({
  beforeLoad: requireAuth({ returnTo: '/dashboard' }),
  component: Dashboard,
});

function Dashboard() {
  const user = useUser();
  return <h1>Welcome, {user?.name}!</h1>;
}
```

`requireAuth` runs in `beforeLoad`, that is, before the route's loader or component ever execute. An unauthenticated visitor is redirected to log in and sent back to `/dashboard` afterward.

## Reading the Session on the Server

Server functions and API routes reach the session through the free functions exported from `/server`, passing your `auth0` instance as the first argument:

```js
import { createServerFn } from '@tanstack/react-start';
import { getSession, getAccessToken } from '@auth0/auth0-tanstack-start-react/server';
import { auth0 } from '../auth.server';

const getMyOrders = createServerFn().handler(async () => {
  const session = await getSession(auth0);
  const token = await getAccessToken(auth0);
  // call your API with `token`, scoped to `session.user`
});
```

If you are coming from another Auth0 SDK, note the shape: it is `getSession(auth0)`, not `auth0.getSession()`.

## Beyond the Basics

The SDK's [examples directory](https://github.com/auth0/auth0-tanstack-start-react/tree/main/examples) includes a `passkeys` app alongside the basic OIDC example, showing how to layer WebAuthn-based passwordless login on top of the same session model. Organizations, MFA, and API scope checks (`withApiOrg`, `withApiScopes`) are available through the [same middleware and guard pattern](https://auth0.com/blog/stop-building-mfa-from-scratch ) shown above, so adding them does not mean learning a new mental model, just a new guard.

## Try It

The fastest way to see it end to end is the [official quickstart](https://auth0.com/docs/quickstart/webapp/tanstack-start), which scaffolds a fresh TanStack Start app and adds the SDK step by step. For the full API surface, including the middleware and server-helper reference, see the [SDK README on GitHub](https://github.com/auth0/auth0-tanstack-start-react).

If you do not already have an Auth0 account yet, [create one for free](https://a0.to/blog_signup).