TanStack React Start Quickstart

Before you start

Set up a Clerk application

Example repository

TanStack React Start Quickstart Repo

Create a new TanStack React Start app

If you don't already have a TanStack React Start app, run the following commands to create a new one.

npm

pnpm

yarn

bun

terminal

npm create @tanstack/start@latest clerk-tanstack-react-start
cd clerk-tanstack-react-start
npm install

terminal

pnpm create @tanstack/start clerk-tanstack-react-start
cd clerk-tanstack-react-start
pnpm install

terminal

yarn create @tanstack/start clerk-tanstack-react-start
cd clerk-tanstack-react-start
yarn install

terminal

bunx @tanstack/create-start@latest clerk-tanstack-react-start
cd clerk-tanstack-react-start
bun install

Install `@clerk/tanstack-react-start`

The Clerk TanStack React Start SDK gives you access to prebuilt components, hooks, and helpers to make user authentication easier.

Run the following command to install the SDK:

npm

pnpm

yarn

bun

terminal

npm install @clerk/tanstack-react-start

terminal

pnpm add @clerk/tanstack-react-start

terminal

yarn add @clerk/tanstack-react-start

terminal

bun add @clerk/tanstack-react-start

Set your Clerk API keys

.env

VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY

Add `clerkMiddleware()` to your app

clerkMiddleware() grants you access to user authentication state throughout your app. It also allows you to protect specific routes from unauthenticated users. To add clerkMiddleware() to your app, follow these steps:

Create a src/start.ts file with the following code:

src/start.ts

import { clerkMiddleware } from '@clerk/tanstack-react-start/server'
import { createStart } from '@tanstack/react-start'

export const startInstance = createStart(() => {
  return {
    requestMiddleware: [clerkMiddleware()],
  }
})

By default, clerkMiddleware() will not protect any routes. All routes are public and you must opt-in to protection for routes. See the clerkMiddleware() reference to learn how to require authentication for specific routes.

Add `<ClerkProvider>` to your app

The <ClerkProvider> component provides session and user context to Clerk's hooks and components. It's recommended to wrap your entire app at the entry point with <ClerkProvider> to make authentication globally accessible. See the reference docs for other configuration options.

Add the <ClerkProvider> component to your app's root route, as shown in the following example:

src/routes/__root.tsx

+ import { ClerkProvider } from '@clerk/tanstack-react-start'
32 lines collapsed
  import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
  import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
  
  import Header from '../components/Header'
  
  import appCss from '../styles.css?url'
  
  export const Route = createRootRoute({
    head: () => ({
      meta: [
        {
          charSet: 'utf-8',
        },
        {
          name: 'viewport',
          content: 'width=device-width, initial-scale=1',
        },
        {
          title: 'TanStack Start Starter',
        },
      ],
      links: [
        {
          rel: 'stylesheet',
          href: appCss,
        },
      ],
    }),
  
    shellComponent: RootDocument,
  })
  
  function RootDocument({ children }: { children: React.ReactNode }) {
    return (
      <html lang="en">
        <head>
          <HeadContent />
        </head>
        <body>
+         <ClerkProvider>
            <Header />
            {children}
+         </ClerkProvider>
          <TanStackRouterDevtools />
          <Scripts />
        </body>
      </html>
    )
  }

Protect your pages

Client-side

To protect your pages on the client-side, you can use Clerk's prebuilt control components that control the visibility of content based on the user's authentication state.

The following example uses the following components:

<SignedIn>: Children of this component can only be seen while signed in.
<SignedOut>: Children of this component can only be seen while signed out.
<UserButton />: Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.
<SignInButton />: An unstyled component that links to the sign-in page. In this example, since no props or environment variables are set for the sign-in URL, this component links to the Account Portal sign-in page.
<SignUpButton />: An unstyled component that links to the sign-up page. In this example, since no props or environment variables are set for the sign-up URL, this component links to the Account Portal sign-up page.

src/routes/index.tsx

import {
  SignedIn,
  UserButton,
  SignedOut,
  SignInButton,
  SignUpButton,
} from '@clerk/tanstack-react-start'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({
  component: Home,
})

function Home() {
  return (
    <div>
      <h1>Index Route</h1>
      <header>
        {/* Show the sign-in and sign-up buttons when the user is signed out */}
        <SignedOut>
          <SignInButton />
          <SignUpButton />
        </SignedOut>
        {/* Show the user button when the user is signed in */}
        <SignedIn>
          <UserButton />
        </SignedIn>
      </header>
    </div>
  )
}

Server-side

To protect your routes, create a server function that checks the user's authentication state via the auth() method. If the user is not authenticated, they are redirected to a sign-in page. If authenticated, the user's userId is passed to the route, allowing access to the <Home /> component, which welcomes the user and displays their userId. The beforeLoad() method ensures authentication is checked before loading the page, and the loader() method returns the user data for use in the component.

Tip

Ensure that your app has the TanStack Start server handler configured in order for your server routes to work.

src/routes/index.tsx

import { createFileRoute, redirect } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start'
import { auth } from '@clerk/tanstack-react-start/server'

const authStateFn = createServerFn().handler(async () => {
  const { isAuthenticated, userId } = await auth()

  if (!isAuthenticated) {
    // This will error because you're redirecting to a path that doesn't exist yet
    // You can create a sign-in route to handle this
    // See https://clerk.com/docs/tanstack-react-start/guides/development/custom-sign-in-or-up-page
    throw redirect({
      to: '/sign-in',
    })
  }

  return { userId }
})

export const Route = createFileRoute('/')({
  component: Home,
  beforeLoad: async () => await authStateFn(),
  loader: async ({ context }) => {
    return { userId: context.userId }
  },
})

function Home() {
  const state = Route.useLoaderData()

  return <h1>Welcome! Your ID is {state.userId}!</h1>
}

Run your project

Run your project with the following command:

npm

pnpm

yarn

bun

terminal

npm run dev

terminal

pnpm run dev

terminal

yarn dev

terminal

bun run dev

Create your first user

Visit your app's homepage at http://localhost:3000.
Select "Sign up" on the page and authenticate to create your first user.

Edit on GitHub

TanStack React Start Quickstart

Before you start

Example repository

Create a new TanStack React Start app

Install `@clerk/tanstack-react-start`

Set your Clerk API keys

Add `clerkMiddleware()` to your app

Add `<ClerkProvider>` to your app

Protect your pages

Client-side

Server-side

Run your project

Create your first user

Next steps

Prebuilt components

Customization & localization

Create a custom sign-in-or-up page

Protect content and read user data

Client-side helpers (hooks)

Clerk TanStack React Start SDK Reference

TanStack React Start Quickstart

Before you start

Example repository

Feedback