clerk · wobsoriano · Jun 25, 2025 · Jun 17, 2025 · Jun 17, 2025 · Jun 17, 2025
@@ -1,4 +1,4 @@
 > [!CAUTION]
-> The entire session token has a max size of 4kb. Exceeding this size can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications.
+> The entire session token has a max size of 4KB. Exceeding this size can have adverse effects, including a possible infinite redirect loop for users who exceed this size in Next.js applications.
 > It's recommended to move particularly large claims out of the JWT and fetch these using a separate API call from your backend.
 > [Learn more](/docs/backend-requests/resources/session-tokens#size-limitations).
@@ -190,15 +190,15 @@ This guide will show you how to customize a session token to include additional
     <Tab>
       For Tanstack React Start, the `Auth` object is accessed using the `getAuth()` function. [Learn more about using `getAuth()`](/docs/references/tanstack-react-start/read-session-data#server-side).
 
-      ```ts {{ filename: 'app/routes/api/example.ts' }}
+      ```ts {{ filename: 'src/routes/api/example.ts' }}
       import { getAuth } from '@clerk/tanstack-react-start/server'
       import { json } from '@tanstack/react-start'
-      import { createAPIFileRoute } from '@tanstack/react-start/api'
+      import { createServerFileRoute } from '@tanstack/react-start/server'
 
-      export const Route = createAPIFileRoute('/api/example')({
-        GET: async ({ req, params }) => {
+      export const ServerRoute = createServerFileRoute().methods({
+        GET: async ({ request, params }) => {
           // Use `getAuth()` to retrieve the user's ID and session claims
-          const { userId, sessionClaims } = await getAuth(req)
+          const { userId, sessionClaims } = await getAuth(request)
 
           // Protect the API route by checking if the user is signed in
           if (!userId) {

@@ -207,10 +207,10 @@ The following example includes basic implementation of the `<SignIn />` componen
     import { createFileRoute } from '@tanstack/react-router'
 
     export const Route = createFileRoute('/sign-in')({
-      component: SignIn,
+      component: SignInPage,
     })
 
-    function SignIn() {
+    function SignInPage() {
       return <SignIn />
     }
     ```

@@ -181,10 +181,10 @@ The following example includes basic implementation of the `<SignUp />` componen
     import { createFileRoute } from '@tanstack/react-router'
 
     export const Route = createFileRoute('/sign-up')({
-      component: SignUp,
+      component: SignUpPage,
     })
 
-    function SignUp() {
+    function SignUpPage() {
       return <SignUp />
     }
     ```

@@ -116,10 +116,9 @@ The recommended approach is to wrap your entire app with `<ClerkProvider>` at th
   </Tab>
 
   <Tab>
-    ```tsx {{ filename: 'app/routes/__root.tsx', ins: [4, 18, 29] }}
-    import { Outlet, createRootRoute } from '@tanstack/react-router'
-    import { Meta, Scripts } from '@tanstack/react-start'
+    ```tsx {{ filename: 'src/routes/__root.tsx', ins: [3, 17, 27] }}
     import * as React from 'react'
+    import { HeadContent, Outlet, Scripts, createRootRoute } from '@tanstack/react-router'
     import { ClerkProvider } from '@clerk/tanstack-react-start'
 
     export const Route = createRootRoute({
@@ -137,7 +136,7 @@ The recommended approach is to wrap your entire app with `<ClerkProvider>` at th
         <ClerkProvider>
           <html>
             <head>
-              <Meta />
+              <HeadContent />
             </head>
             <body>
               {children}

@@ -111,10 +111,10 @@ The following example includes a basic implementation of the `<CreateOrganizatio
     import { createFileRoute } from '@tanstack/react-router'
 
     export const Route = createFileRoute('/create-organization')({
-      component: CreateOrganization,
+      component: CreateOrganizationPage,
     })
 
-    function CreateOrganization() {
+    function CreateOrganizationPage() {
       return <CreateOrganization />
     }
     ```

@@ -138,10 +138,10 @@ The `<OrganizationList />` component accepts the following properties, all of wh
     import { createFileRoute } from '@tanstack/react-router'
 
     export const Route = createFileRoute('/organizations')({
-      component: OrganizationList,
+      component: OrganizationListPage,
     })
 
-    function OrganizationList() {
+    function OrganizationListPage() {
       return (
         <OrganizationList
           afterCreateOrganizationUrl={(org) => `/organization/${org.slug}`}

@@ -110,10 +110,10 @@ The `<OrganizationProfile />` component accepts the following properties, all of
     import { createFileRoute } from '@tanstack/react-router'
 
     export const Route = createFileRoute('/organization-profile')({
-      component: OrganizationProfile,
+      component: OrganizationProfilePage,
     })
 
-    function OrganizationProfile() {
+    function OrganizationProfilePage() {
       return <OrganizationProfile />
     }
     ```

@@ -153,10 +153,10 @@ The `<OrganizationSwitcher />` component accepts the following properties, all o
     import { createFileRoute } from '@tanstack/react-router'
 
     export const Route = createFileRoute('/organization-switcher')({
-      component: OrganizationSwitcher,
+      component: OrganizationSwitcherPage,
     })
 
-    function OrganizationSwitcher() {
+    function OrganizationSwitcherPage() {
       return <OrganizationSwitcher />
     }
     ```

@@ -109,7 +109,7 @@ The following example includes a basic implementation of the `<PricingTable />`
     import { createFileRoute } from '@tanstack/react-router'
 
     export const Route = createFileRoute('/pricing')({
-      component: PricingTable,
+      component: PricingPage,
     })
 
     function PricingPage() {

@@ -104,10 +104,10 @@ All props are optional.
     import { createFileRoute } from '@tanstack/react-router'
 
     export const Route = createFileRoute('/user-profile')({
-      component: UserProfile,
+      component: UserProfilePage,
     })
 
-    function UserProfile() {
+    function UserProfilePage() {
       return <UserProfile />
     }
     ```

@@ -95,7 +95,7 @@ The following example includes a basic implementation of the `<Waitlist />` comp
     import { createFileRoute } from '@tanstack/react-router'
 
     export const Route = createFileRoute('/waitlist')({
-      component: Waitlist,
+      component: WaitlistPage,
     })
 
     function WaitlistPage() {

@@ -73,18 +73,16 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat
 
   Clerk's [`createClerkHandler()`](/docs/references/tanstack-react-start/create-clerk-handler) configures Clerk to handle authentication state for TanStack routes, allowing you to easily access user session information within your app.
 
-  Update your app's SSR entrypoint by wrapping `createStartHandler()` in `createClerkHandler()`, as shown in the following example:
+  Create a custom handler and wrap it with `createClerkHandler()`, as shown in the following example:
 
-  ```tsx {{ filename: 'app/ssr.tsx' }}
+  ```tsx {{ filename: 'src/server.ts' }}
   import { createStartHandler, defaultStreamHandler } from '@tanstack/react-start/server'
-  import { getRouterManifest } from '@tanstack/react-start/router-manifest'
   import { createRouter } from './router'
   import { createClerkHandler } from '@clerk/tanstack-react-start/server'
 
   export default createClerkHandler(
     createStartHandler({
       createRouter,
-      getRouterManifest,
     }),
   )(defaultStreamHandler)
   ```
@@ -95,10 +93,9 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat
 
   Add the `<ClerkProvider>` component to your app's root route, as shown in the following example:
 
-  ```tsx {{ filename: 'app/routes/__root.tsx', ins: [4, 18, 28] }}
-  import { Outlet, createRootRoute } from '@tanstack/react-router'
-  import { Meta, Scripts } from '@tanstack/react-start'
+  ```tsx {{ filename: 'src/routes/__root.tsx', ins: [3, 17, 27] }}
   import * as React from 'react'
+  import { HeadContent, Outlet, Scripts, createRootRoute } from '@tanstack/react-router'
   import { ClerkProvider } from '@clerk/tanstack-react-start'
 
   export const Route = createRootRoute({
@@ -116,7 +113,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat
       <ClerkProvider>
         <html>
           <head>
-            <Meta />
+            <HeadContent />
           </head>
           <body>
             {children}
@@ -141,15 +138,8 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat
   - [`<UserButton />`](/docs/components/user/user-button): Shows the signed-in user's avatar. Selecting it opens a dropdown menu with account management options.
   - [`<SignInButton />`](/docs/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page. In this example, since no props or [environment variables](/docs/deployments/clerk-environment-variables) are set for the sign-in URL, this component links to the [Account Portal sign-in page](/docs/account-portal/overview#sign-in).
 
-  ```tsx {{ filename: 'app/routes/index.tsx' }}
-  import {
-    SignedIn,
-    UserButton,
-    SignOutButton,
-    SignedOut,
-    SignInButton,
-    SignUpButton,
-  } from '@clerk/tanstack-react-start'
+  ```tsx {{ filename: 'src/routes/index.tsx' }}
+  import { SignedIn, UserButton, SignedOut, SignInButton } from '@clerk/tanstack-react-start'
   import { createFileRoute } from '@tanstack/react-router'
 
   export const Route = createFileRoute('/')({
@@ -178,9 +168,9 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat
   To protect your routes, create a [server function](https://tanstack.com/router/latest/docs/framework/react/start/server-functions) that checks the user's authentication state via the [`getAuth()`](/docs/references/tanstack-react-start/get-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()`](https://tanstack.com/router/latest/docs/framework/react/api/router/RouteOptionsType#beforeload-method) method ensures authentication is checked before loading the page, and the [`loader()`](https://tanstack.com/router/latest/docs/framework/react/api/router/RouteOptionsType#loader-method) method returns the user data for use in the component.
 
   > [!TIP]
-  > Ensure that your app has the [TanStack Start API entry handler](https://tanstack.com/router/latest/docs/framework/react/start/api-routes#setting-up-the-entry-handler) configured in order for your API routes to work.
+  > Ensure that your app has the [TanStack Start server handler](https://tanstack.com/start/latest/docs/framework/react/server-routes#handling-server-route-requests) configured in order for your server routes to work.
 
-  ```tsx {{ filename: 'app/routes/index.tsx' }}
+  ```tsx {{ filename: 'src/routes/index.tsx' }}
   import { createFileRoute, redirect } from '@tanstack/react-router'
   import { createServerFn } from '@tanstack/react-start'
   import { getAuth } from '@clerk/tanstack-react-start/server'
@@ -196,7 +186,7 @@ description: Learn how to use Clerk to quickly and easily add secure authenticat
       // You can create a sign-in route to handle this
       // See https://clerk.com/docs/references/tanstack-start/custom-sign-in-or-up-page
       throw redirect({
-        to: '/sign-in/$',
+        to: '/sign-in',
       })
     }
 

@@ -219,9 +219,9 @@ To access a resource, you must first instantiate a `clerkClient` instance.
         ```tsx {{ filename: 'app/routes/api/example.tsx' }}
         import { createClerkClient } from '@clerk/backend'
         import { json } from '@tanstack/react-start'
-        import { createAPIFileRoute } from '@tanstack/react-start/api'
+        import { createServerFileRoute } from '@tanstack/react-start/server'
 
-        export const Route = createAPIFileRoute('/api/example')({
+        export const ServerRoute = createServerFileRoute().methods({
           GET: async ({ request, params }) => {
             const clerkClient = createClerkClient({ secretKey: import.meta.env.CLERK_SECRET_KEY })
 

@@ -280,9 +280,9 @@ The `Auth` object is not available in the frontend. To use the `getToken()` meth
     ```ts {{ filename: 'app/routes/api/example.ts' }}
     import { getAuth } from '@clerk/tanstack-react-start/server'
     import { json } from '@tanstack/react-start'
-    import { createAPIFileRoute } from '@tanstack/react-start/api'
+    import { createServerFileRoute } from '@tanstack/react-start/server'
 
-    export const Route = createAPIFileRoute('/api/example')({
+    export const ServerRoute = createServerFileRoute().methods({
       GET: async ({ req, params }) => {
         const { userId, getToken } = await getAuth(req)
 

@@ -11,16 +11,14 @@ The `createClerkHandler()` function configures Clerk to handle authentication st
 
 The following example demonstrates how to use `createClerkHandler()` to configure Clerk in your TanStack React Start application.
 
-```tsx {{ filename: 'app/ssr.tsx' }}
+```tsx {{ filename: 'src/server.ts' }}
 import { createStartHandler, defaultStreamHandler } from '@tanstack/react-start/server'
-import { getRouterManifest } from '@tanstack/react-start/router-manifest'
 import { createRouter } from './router'
 import { createClerkHandler } from '@clerk/tanstack-react-start/server'
 
 export default createClerkHandler(
   createStartHandler({
     createRouter,
-    getRouterManifest,
   }),
 )(defaultStreamHandler)
 ```
@@ -15,7 +15,7 @@ To set up separate sign-in and sign-up pages, follow this guide, and then follow
 
   The following example demonstrates how to render the [`<SignIn />`](/docs/components/authentication/sign-in) component on a dedicated page using the [TanStack Router catch-all route](https://tanstack.com/router/latest/docs/framework/react/routing/routing-concepts#splat--catch-all-routes).
 
-  ```tsx {{ filename: 'app/routes/sign-in.$.tsx' }}
+  ```tsx {{ filename: 'src/routes/sign-in.$.tsx' }}
   import { SignIn } from '@clerk/tanstack-react-start'
   import { createFileRoute } from '@tanstack/react-router'
 
@@ -30,16 +30,12 @@ To set up separate sign-in and sign-up pages, follow this guide, and then follow
 
   ## Configure your sign-in-or-up page
 
-  - Set the `CLERK_SIGN_IN_URL` environment variable to tell Clerk where the `<SignIn />` component is being hosted.
-  - Set `CLERK_SIGN_IN_FALLBACK_REDIRECT_URL` as a fallback URL incase users visit the `/sign-in` route directly.
-  - Set `CLERK_SIGN_UP_FALLBACK_REDIRECT_URL` as a fallback URL incase users select the 'Don't have an account? Sign up' link at the bottom of the component.
+  Set the `CLERK_SIGN_IN_URL` environment variable to tell Clerk where the `<SignIn />` component is being hosted.
 
-  Learn more about these environment variables and how to customize Clerk's redirect behavior in the [dedicated guide](/docs/guides/custom-redirects).
+  There are other environment variables that you can set to customize Clerk's redirect behavior, such as `CLERK_SIGN_IN_FORCE_REDIRECT_URL`. Learn more about these environment variables and how to customize Clerk's redirect behavior in the [dedicated guide](/docs/guides/custom-redirects).
 
   ```env {{ filename: '.env' }}
   CLERK_SIGN_IN_URL=/sign-in
-  CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/
-  CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/
   ```
 
   ## Visit your new page

@@ -15,7 +15,7 @@ To set up a single sign-in-or-up page, follow the [custom sign-in-or-up page gui
 
   The following example demonstrates how to render the [`<SignUp />`](/docs/components/authentication/sign-up) component on a dedicated sign-up page using the [TanStack Router catch-all route](https://tanstack.com/router/latest/docs/framework/react/routing/routing-concepts#splat--catch-all-routes).
 
-  ```tsx {{ filename: 'app/routes/sign-up.$.tsx' }}
+  ```tsx {{ filename: 'src/routes/sign-up.$.tsx' }}
   import { SignUp } from '@clerk/tanstack-react-start'
   import { createFileRoute } from '@tanstack/react-router'
 
@@ -31,15 +31,11 @@ To set up a single sign-in-or-up page, follow the [custom sign-in-or-up page gui
   ## Configure your sign-up page
 
   - Set the `CLERK_SIGN_UP_URL` environment variable to tell Clerk where the `<SignUp />` component is being hosted.
-  - Set `CLERK_SIGN_UP_FALLBACK_REDIRECT_URL` as a fallback URL incase users visit the `/sign-up` route directly.
-  - Set `CLERK_SIGN_IN_FALLBACK_REDIRECT_URL` as a fallback URL incase users select the 'Already have an account? Sign in' link at the bottom of the component.
 
-  Learn more about these environment variables and how to customize Clerk's redirect behavior in the [dedicated guide](/docs/guides/custom-redirects).
+  There are other environment variables that you can set to customize Clerk's redirect behavior, such as `CLERK_SIGN_UP_FORCE_REDIRECT_URL`. Learn more about these environment variables and how to customize Clerk's redirect behavior in the [dedicated guide](/docs/guides/custom-redirects).
 
   ```env {{ filename: '.env' }}
   CLERK_SIGN_UP_URL=/sign-up
-  CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/
-  CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/
   ```
 
   ## Visit your new pages