From 3bb817e993b3a434962fc44a0c228e21dfd53f4b Mon Sep 17 00:00:00 2001 From: Tamal Anwar Chowdhury Date: Tue, 7 Apr 2026 21:24:10 +0600 Subject: [PATCH 1/2] Initial commit, copy from Yoshify --- .../developer-tools/sdks/backend/tsr-sdk.mdx | 324 ++++++++++++++++++ 1 file changed, 324 insertions(+) create mode 100644 src/content/docs/developer-tools/sdks/backend/tsr-sdk.mdx diff --git a/src/content/docs/developer-tools/sdks/backend/tsr-sdk.mdx b/src/content/docs/developer-tools/sdks/backend/tsr-sdk.mdx new file mode 100644 index 000000000..5f1e31bc2 --- /dev/null +++ b/src/content/docs/developer-tools/sdks/backend/tsr-sdk.mdx @@ -0,0 +1,324 @@ +--- +page_id: 7eb15b27-864c-49fd-a12e-3f4d415f47fa +title: TanStack React Start SDK +sidebar: + order: 10 +tableOfContents: + maxHeadingLevel: 3 +head: + - tag: meta + attrs: + property: "og:image" + content: "https://kinde.com/assets/images/open-graph/DOCS-SSI-SDK_NEXT.png" +--- + + + +This SDK is for TanStack React Start version `v1.132.25` or higher. + +New to Kinde? [Get started here](/get-started/guides/first-things-first/) + +## Install for a new project + +The easiest way to get started is to use the [TanStack React Start starter kit](TODO) + +## **Install for an existing project** + + + +## **Set callback URLs** + +1. In Kinde, go to **Settings > Applications > [Your app] > View details**. +2. Add your callback URLs in the relevant fields. For example: + - Allowed callback URLs (also known as redirect URIs) - for example `http://localhost:3000/api/auth/callback` + - Allowed logout redirect URLs - for example `http://localhost:3000` +3. Select **Save**. + +## **Configure environment variables** + +Put these variables in a `.env.local` file in the root of your app. You can find these variables on your Kinde **Settings > Applications > [Your app] > View details** page. +- `VITE_KINDE_CLIENT_ID` - Your business’s unique ID on Kinde +- `KINDE_CLIENT_SECRET` - Your business’s secret key (do not share) +- `VITE_KINDE_ISSUER_URL` - your kinde domain +- `VITE_KINDE_SITE_URL` - where your app is running +- `KINDE_POST_LOGOUT_REDIRECT_URL` - where you want users to be redirected to after logging out. Make sure this URL is under your allowed logout redirect URLs. +- `KINDE_POST_LOGIN_REDIRECT_URL` - where you want users to be redirected to after authenticating. + + + +Replace the information in the example with your own information. You might also set different URLs depending where your project is running. They need to match the callback URLs you entered in Kinde, above. + +```shell +VITE_KINDE_CLIENT_ID= +KINDE_CLIENT_SECRET= +VITE_KINDE_ISSUER_URL=https://.kinde.com +VITE_KINDE_SITE_URL=http://localhost:3000 +KINDE_POST_LOGOUT_REDIRECT_URL=http://localhost:3000 +KINDE_POST_LOGIN_REDIRECT_URL=http://localhost:3000/dashboard +``` + +## **Set up Kinde Auth Route Handlers** + +Create the following file `src/routes/api.auth.$.ts` inside your project. Inside the file, insert the following code: + +```tsx +import { kindeAuthHandler } from "@kinde/kinde-auth-tanstack-start/server";Collapse commentComment on line R67DanielRivers commented on Nov 9, 2025 DanielRiverson Nov 9, 2025MemberMore actionsThis will be @kinde/tsrI thinkReactWrite a replyResolve comment +import { createFileRoute } from "@tanstack/react-router"; + +export const Route = createFileRoute("/api/auth/$")({ + server: { + handlers: { + GET: async ({ request }) => kindeAuthHandler(request), + POST: async ({ request }) => kindeAuthHandler(request), + }, + }, +}); +``` + +This will handle Kinde Auth endpoints in your app. + +## **Customising Kinde Auth API paths** + +The default path for the Kinde Auth API is `/api/auth`. If your application uses a custom base path for your API, you can override this setting by setting the following variable in your `.env` file: + +```bash +KINDE_AUTH_API_PATH="/my/custom/path" +``` + +You can also customise the Kinde Auth API sub-paths by setting the following variables in your `.env` file: + +- `KINDE_AUTH_LOGIN_ROUTE` - defaults to `login` +- `KINDE_AUTH_LOGOUT_ROUTE` - defaults to `logout` +- `KINDE_AUTH_REGISTER_ROUTE` - defaults to `register` +- `KINDE_AUTH_CREATE_ORG_ROUTE` - defaults to `create-org` +- `KINDE_AUTH_HEALTH_ROUTE` - defaults to `health` +- `KINDE_AUTH_SETUP_ROUTE` - defaults to `setup` + +#### **Example** + +Given the following `.env` file: + +```bash +KINDE_AUTH_API_PATH="/my/custom/path" +KINDE_AUTH_LOGIN_ROUTE="app_login" +``` + +The Kinde login route for your application will be `/my/custom/path/app_login`. + + + +## **Set up middleware** + +Middleware is used to protect the server-side of your application, keep tokens refreshed, and define route rules for protecting your application on both client and server. + +All paths are public by default, and must be explicitly opted-in for protection using route rules. + + + +#### **Middleware configuration** + +Create a `start.ts` file in your project's root directory and add the following code: +```ts +import { createStart } from '@tanstack/react-start'; +import { createKindeGlobalMiddleware } from '@kinde/kinde-auth-tanstack-start/server'; + +export const startInstance = createStart(() => { + return { + requestMiddleware: [createKindeGlobalMiddleware({ + routeRules: [ + ] + })] + } +}); +``` + +#### **Defining route rules** + +The route rules array on `createKindeGlobalMiddleware` is used to define the rules for protecting your application on both client and server. + +It defines which pages should be protected, how redirection should be handled, and whether to narrow protection checks down to specific permissions, roles or entitlements. + +Route rule paths support a glob pattern syntax for matching routes. + +**Examples** +- `/admin/*` - matches `/admin` and anything after, e.g., `/admin/users`, `/admin/settings` +- `*/faq` - matches any route that ends with `/faq`, e.g., `/some-route/faq`, `/another-route/faq` +- `/admin/*/settings` - matches `/admin/users/settings`, `/admin/org/settings`, etc. + +An example of route rules: +```ts +import { createStart } from '@tanstack/react-start'; +import { createKindeGlobalMiddleware } from '@kinde/kinde-auth-tanstack-start/server'; + +export const startInstance = createStart(() => { + return { + requestMiddleware: [createKindeGlobalMiddleware({ + routeRules: [ + { + // Protect the dashboard route and all its children + path: '/dashboard/*', + // Redirect to this page if the authentication check fails. + redirectTo: '/' + }, + { + // Protect the admin route and all its children, also ensuring the user has the 'read:admin' permission or the 'admin' role + path: '/admin/*', + redirectTo: '/', + has: { + permissions: ['read:admin'], + roles: ['admin'], + } + }, + { + // Protect the pro route and all its children, also ensuring the user has the 'pro' billing entitlement + path: '/pro/*', + redirectTo: '/', + has: { + billingEntitlements: ['pro'], + } + }, + { + // Protect the new wip page route, also ensuring the user has the 'new-wip-page-access' feature flag + path: '*/new-wip-page', + redirectTo: '/current-page', + has: { + featureFlags: ['new-wip-page-access'], + } + } + ] + })] + } +}); +``` + +## **Set up the Kinde Auth Provider** + +In your applications `__root.tsx` file, wrap your app in the Kinde Auth Provider. This will give you access to the Kinde Auth data in your app and will ensure that the tokens are refreshed when needed. + +```tsx +import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from '@tanstack/react-router'; +import { KindeTanstackProvider } from '@kinde/kinde-auth-tanstack-start'; + +export const Route = createRootRouteWithContext()({ + component: RootComponent, +}); + +function RootComponent() { + return ( + + + + ) +} + + +function RootDocument({ children }: { children: React.ReactNode }) { + return ( + + + + + + + {children} + + + + + ); +} +``` + +## Protecting routes on the client + +In order to protect routes on the client, you need to use the `protect` utility in a routes `beforeLoad` function. It will use the route rules you've defined in your middleware. + +```tsx +export const Route = createFileRoute('/protected/')({ + beforeLoad: async (ctx) => { + // You must pass the path of the route in order for your route rules to be applied. + await protect(ctx.location.pathname); + + // Note that any code you supply after protect will not be executed if the route is protected as the user is redirected. + }, +}); +``` + +## Authentication + +### Sign up and sign in + +The SDK ships with `` and `` components which can be used to start the auth flow. + +```jsx +import {RegisterLink, LoginLink} from "@kinde-oss/kinde-auth-nextjs/components"; + +... + +Sign in +Sign up +``` + +### Redirecting after authentication + +**Static redirect** + +If you want to redirect users to a certain page after logging in, you can set the `KINDE_POST_LOGIN_REDIRECT_URL` environment variable in your `.env.local` file. + +**Dynamic redirect** + +You can also set a `postLoginRedirectURL` parameter to tell us where to redirect after authenticating. + +```jsx +import {RegisterLink, LoginLink} from "@kinde-oss/kinde-auth-nextjs/components"; + +... + +Sign in +Sign up +``` + +This appends `post_login_redirect_url` to the search params when redirecting to Kinde Auth. You can achieve the same result as above, like this: + +```jsx +import { redirect } from "next/navigation"; +... + +redirect('/api/auth/login?post_login_redirect_url=/dashboard') + +... +``` + +### Logout + +This is implemented in much the same way as signing up or signing in. A component is provided for you. + +```jsx +import {LogoutLink} from "@kinde-oss/kinde-auth-nextjs/components"; + +... + +Log out +``` + +## Kinde Auth data - Server + +## Debug mode + +In debug mode you will see more logs in your console that may help with debugging and assist with support. + +```tsx +// .env + +KINDE_DEBUG_MODE = true; +``` From df329c235ef952ec56a30b5d7dbffb76401f961b Mon Sep 17 00:00:00 2001 From: Tamal Anwar Chowdhury Date: Tue, 7 Apr 2026 22:29:11 +0600 Subject: [PATCH 2/2] update the doc page layout --- .../developer-tools/sdks/backend/tsr-sdk.mdx | 500 +++++++++++------- 1 file changed, 296 insertions(+), 204 deletions(-) diff --git a/src/content/docs/developer-tools/sdks/backend/tsr-sdk.mdx b/src/content/docs/developer-tools/sdks/backend/tsr-sdk.mdx index 5f1e31bc2..1fa1b7115 100644 --- a/src/content/docs/developer-tools/sdks/backend/tsr-sdk.mdx +++ b/src/content/docs/developer-tools/sdks/backend/tsr-sdk.mdx @@ -1,73 +1,104 @@ --- page_id: 7eb15b27-864c-49fd-a12e-3f4d415f47fa title: TanStack React Start SDK +description: "Install and configure the Kinde SDK for TanStack Start: environment variables, auth routes, middleware, route protection, and client hooks." sidebar: order: 10 tableOfContents: maxHeadingLevel: 3 +relatedArticles: + - 7d311fcf-ca33-49ec-9286-419da4a91f41 + - 3747b2ea-82a0-4620-b71e-61a0622175e1 + - 3a5cbe42-d4c2-4f41-a243-a4852fdcf4a5 head: - tag: meta attrs: property: "og:image" content: "https://kinde.com/assets/images/open-graph/DOCS-SSI-SDK_NEXT.png" +topics: + - developer-tools + - sdks + - tanstack + - backend +sdk: + - tanstack-start +languages: + - javascript + - typescript + - jsx + - tsx +audience: developers +complexity: intermediate +keywords: + - TanStack Start + - TanStack Router + - authentication + - route protection + - environment variables + - Vite +updated: 2026-04-07 +featured: false +deprecated: false +ai_summary: Install and configure the Kinde SDK for TanStack Start with auth handlers, global middleware, KindeTanstackProvider, useKindeAuth, server loaders, and protect utilities. --- - +Official Kinde SDK for [TanStack Start](https://tanstack.com/start)—a full-stack React framework on [TanStack Router](https://tanstack.com/router). This guide covers a new or existing app on TanStack Start `v1.132.25` or higher (with `@tanstack/react-router` and `@tanstack/react-start`). + +### What you need + +- A [Kinde](https://app.kinde.com/) account (Sign up for free) +- [Node.js](https://nodejs.org/) version 20 or higher +- A TanStack Start project using `@tanstack/react-router` and `@tanstack/react-start` **v1.132.25** or higher -This SDK is for TanStack React Start version `v1.132.25` or higher. +## Quickstart -New to Kinde? [Get started here](/get-started/guides/first-things-first/) +### 1. Create a new TanStack Start project + +```bash +npx @tanstack/cli@latest create kinde-tanstack-app --yes +``` -## Install for a new project +### 2. Create a Kinde app and set callback URLs -The easiest way to get started is to use the [TanStack React Start starter kit](TODO) +1. In Kinde, select **Add new application**, select **Back-end application > Other back end** +2. Go to **View details** and copy the **Domain**, **Client ID** and **Client secret** values. +2. Add callback URLs, for example: + - **Allowed callback URLs** — `http://localhost:3000/api/auth/callback` + - **Allowed logout redirect URLs** — `http://localhost:3000` +3. Select **Save**. -## **Install for an existing project** +For production, add the same paths using your real domain. - +### 3. Install the Kinde SDK -## **Set callback URLs** + -1. In Kinde, go to **Settings > Applications > [Your app] > View details**. -2. Add your callback URLs in the relevant fields. For example: - - Allowed callback URLs (also known as redirect URIs) - for example `http://localhost:3000/api/auth/callback` - - Allowed logout redirect URLs - for example `http://localhost:3000` -3. Select **Save**. +### 4. Add environment variables -## **Configure environment variables** +Put these in a `.env` file in the project root. Values come from **Details** page in Kinde. -Put these variables in a `.env.local` file in the root of your app. You can find these variables on your Kinde **Settings > Applications > [Your app] > View details** page. -- `VITE_KINDE_CLIENT_ID` - Your business’s unique ID on Kinde -- `KINDE_CLIENT_SECRET` - Your business’s secret key (do not share) -- `VITE_KINDE_ISSUER_URL` - your kinde domain -- `VITE_KINDE_SITE_URL` - where your app is running -- `KINDE_POST_LOGOUT_REDIRECT_URL` - where you want users to be redirected to after logging out. Make sure this URL is under your allowed logout redirect URLs. -- `KINDE_POST_LOGIN_REDIRECT_URL` - where you want users to be redirected to after authenticating. +- **Client ID** → `VITE_KINDE_CLIENT_ID` +- **Client secret** → `KINDE_CLIENT_SECRET` +- **Domain** (issuer) → `VITE_KINDE_ISSUER_URL` +- **Site URL** (where the app runs) → `VITE_KINDE_SITE_URL` -Replace the information in the example with your own information. You might also set different URLs depending where your project is running. They need to match the callback URLs you entered in Kinde, above. +### 5. Add the Kinde auth route handler -```shell -VITE_KINDE_CLIENT_ID= -KINDE_CLIENT_SECRET= -VITE_KINDE_ISSUER_URL=https://.kinde.com -VITE_KINDE_SITE_URL=http://localhost:3000 -KINDE_POST_LOGOUT_REDIRECT_URL=http://localhost:3000 -KINDE_POST_LOGIN_REDIRECT_URL=http://localhost:3000/dashboard -``` +Create `src/routes/api.auth.$.ts`: -## **Set up Kinde Auth Route Handlers** +```bash +touch "src/routes/api.auth.$/route.ts" +``` -Create the following file `src/routes/api.auth.$.ts` inside your project. Inside the file, insert the following code: +Add the following code: ```tsx -import { kindeAuthHandler } from "@kinde/kinde-auth-tanstack-start/server";Collapse commentComment on line R67DanielRivers commented on Nov 9, 2025 DanielRiverson Nov 9, 2025MemberMore actionsThis will be @kinde/tsrI thinkReactWrite a replyResolve comment -import { createFileRoute } from "@tanstack/react-router"; +import { kindeAuthHandler } from "@kinde/kinde-auth-tanstack-start/server" +import { createFileRoute } from "@tanstack/react-router" export const Route = createFileRoute("/api/auth/$")({ server: { @@ -76,153 +107,110 @@ export const Route = createFileRoute("/api/auth/$")({ POST: async ({ request }) => kindeAuthHandler(request), }, }, -}); -``` - -This will handle Kinde Auth endpoints in your app. - -## **Customising Kinde Auth API paths** - -The default path for the Kinde Auth API is `/api/auth`. If your application uses a custom base path for your API, you can override this setting by setting the following variable in your `.env` file: - -```bash -KINDE_AUTH_API_PATH="/my/custom/path" -``` - -You can also customise the Kinde Auth API sub-paths by setting the following variables in your `.env` file: - -- `KINDE_AUTH_LOGIN_ROUTE` - defaults to `login` -- `KINDE_AUTH_LOGOUT_ROUTE` - defaults to `logout` -- `KINDE_AUTH_REGISTER_ROUTE` - defaults to `register` -- `KINDE_AUTH_CREATE_ORG_ROUTE` - defaults to `create-org` -- `KINDE_AUTH_HEALTH_ROUTE` - defaults to `health` -- `KINDE_AUTH_SETUP_ROUTE` - defaults to `setup` - -#### **Example** - -Given the following `.env` file: - -```bash -KINDE_AUTH_API_PATH="/my/custom/path" -KINDE_AUTH_LOGIN_ROUTE="app_login" +}) ``` -The Kinde login route for your application will be `/my/custom/path/app_login`. +This exposes flows such as: - - -## **Set up middleware** - -Middleware is used to protect the server-side of your application, keep tokens refreshed, and define route rules for protecting your application on both client and server. +- `/api/auth/login` +- `/api/auth/logout` +- `/api/auth/callback` +- `/api/auth/register` +- `/api/auth/create-org` -All paths are public by default, and must be explicitly opted-in for protection using route rules. +### 6. Register global auth middleware -