Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(tanstack): add a proper SSR quick start with cookie-based auth (#48105)

Ali Waseemac714e81ba4e
diff --git a/apps/docs/content/guides/auth/server-side/creating-a-client.mdx b/apps/docs/content/guides/auth/server-side/creating-a-client.mdx
index b89c58b9463..ed252782fd5 100644
--- a/apps/docs/content/guides/auth/server-side/creating-a-client.mdx
+++ b/apps/docs/content/guides/auth/server-side/creating-a-client.mdx
@@ -159,6 +159,14 @@ SUPABASE_URL=supabase_project_url
SUPABASE_PUBLISHABLE_KEY=supabase_publishable_key
```
+</TabPanel>
+<TabPanel id="tanstack" label="TanStack Start">
+
+```bash .env.local
+VITE_SUPABASE_URL=supabase_project_url
+VITE_SUPABASE_PUBLISHABLE_KEY=supabase_publishable_key
+```
+
</TabPanel>
</Tabs>
@@ -510,7 +518,7 @@ export async function loader({ request }: LoaderFunctionArgs) {
}
)
- // Use `supabase` here for server-side work, e.g. await supabase.auth.getUser()
+ // Use `supabase` here for server-side work, e.g. await supabase.auth.getClaims()
// Return the environment variables so the browser can create its own client.
return json(
@@ -674,7 +682,7 @@ export async function loader({ request }: LoaderFunctionArgs) {
}
)
- // Use `supabase` here for server-side work, e.g. await supabase.auth.getUser()
+ // Use `supabase` here for server-side work, e.g. await supabase.auth.getClaims()
// Return the env vars so the browser can create its own client.
return data(
@@ -823,6 +831,81 @@ language="typescript"
</TabPanel>
</Tabs>
+</TabPanel>
+<TabPanel id="tanstack" label="TanStack Start">
+
+### Write utility functions to create Supabase clients
+
+TanStack Start renders matched routes on the server by default, so `beforeLoad` and `loader` run server-side on the initial request. Unlike Next.js, this means you don't need a proxy or middleware layer to keep sessions fresh — the server client reads and writes the session cookie directly on each request.
+
+Create a `lib/supabase` folder at the root of your project, or inside the `./src` folder if you are using one, then add a file for each type of client:
+
+1. **Create a browser client in `lib/supabase/client.ts`.** Use it to access Supabase from components that run in the browser.
+2. **Create a server client in `lib/supabase/server.ts`.** Use it to access Supabase from loaders, server functions, and other code that runs only on the server.
+
+<$Partial path="auth_methods.mdx" />
+
+Copy the lib utility functions below into each file:
+
+<div className="mt-12">
+ <$CodeTabs>
+ <$CodeSample
+ path="/auth/tanstack/lib/supabase/client.ts"
+ meta="name=lib/supabase/client.ts"
+ language="typescript"
+ />
+ <$CodeSample
+ path="/auth/tanstack/lib/supabase/server.ts"
+ meta="name=lib/supabase/server.ts"
+ language="typescript"
+ />
+ </$CodeTabs>
+</div>
+
+### Protecting routes
+
+TanStack Start has no global middleware layer, so protect each route explicitly.
+
+To protect your routes:
+
+1. Write a server function, `fetchClaims`, that calls `supabase.auth.getClaims()` and returns the claims, or `null` if the session isn't valid.
+1. Call `fetchClaims` from a layout route's `beforeLoad` hook — for example, `_protected.tsx` — before any nested route renders, and redirect to `/login` when it returns `null`.
+
+<Admonition type="danger">
+
+Skipping the check inside the server function exposes private data to unauthenticated users. `beforeLoad` runs on the server for the initial request and on the client for later navigation, but either way it only gates the route's render — it doesn't stop the server function from being called directly. Because there's no proxy re-checking every request, the server function is the only checkpoint that always runs, so it must call `supabase.auth.getClaims()` to authorize the request itself.
+
+</Admonition>
+
+`getClaims()` validates the JWT signature on every call, the same check the Next.js Proxy relies on. Calling it inside the server function gives TanStack Start's per-route check that same guarantee, because the function runs on every request to a protected route.
+
+<div className="mt-12">
+ <$CodeTabs>
+ <$CodeSample
+ path="/auth/tanstack/lib/supabase/fetch-claims-server-fn.ts"
+ meta="name=lib/supabase/fetch-claims-server-fn.ts"
+ language="typescript"
+ />
+ <$CodeSample
+ path="/auth/tanstack/routes/_protected.tsx"
+ meta="name=routes/_protected.tsx"
+ language="typescript"
+ />
+ </$CodeTabs>
+</div>
+
+Any other server function that returns or mutates private data needs this same check. Don't rely on a route being nested under `_protected` alone.
+
+## Congratulations
+
+You're done! To recap, you've successfully:
+
+- Set up a Supabase client utility to call Supabase from a browser component. You can use this if you need to call Supabase from the browser, for example to set up a realtime subscription.
+- Set up a server client utility to call Supabase from loaders and server functions.
+- Protected a route with `beforeLoad`, backed by a server function that authorizes the request itself.
+
+You can now use any Supabase features from your client or server code!
+
</TabPanel>
</Tabs>
diff --git a/apps/docs/content/guides/getting-started/quickstarts/tanstack.mdx b/apps/docs/content/guides/getting-started/quickstarts/tanstack.mdx
index b59f80d39ad..3fe6ac2a5da 100644
--- a/apps/docs/content/guides/getting-started/quickstarts/tanstack.mdx
+++ b/apps/docs/content/guides/getting-started/quickstarts/tanstack.mdx
@@ -11,7 +11,7 @@ breadcrumb: 'Framework Quickstarts'
Create a TanStack Start app using the official CLI.
```bash
-npm create @tanstack/start@latest my-app -- --package-manager npm --toolchain biome
+npx @tanstack/cli@latest create my-app
```
## 4. Install Agent Skills (optional)
@@ -24,55 +24,87 @@ To install, run the following command in the root of your project:
npx skills add supabase/agent-skills
```
-## 5. Install the Supabase client library
+## 5. Install the Supabase client libraries
-The fastest way to get started is to use the `supabase-js` client library which provides a convenient interface for working with Supabase from a TanStack Start app.
-
-Navigate to the TanStack Start app and install `supabase-js`.
+Navigate to the TanStack Start app and install `supabase-js` and `@supabase/ssr`, the helper package that manages cookie-based sessions for server-side rendering.
```bash
-cd my-app && npm install @supabase/supabase-js
+cd my-app && npm install @supabase/supabase-js @supabase/ssr
```
## 6. Declare Supabase environment variables
-Create a `.env` file in the root of your project and populate with your Supabase connection variables that you can get from the helper below, or [from the project **Connect** panel](/dashboard/project/_?showConnect=true):
+Create a `.env.local` file in the root of your project and populate it with your Supabase connection variables. Get the values from the helper below, or [from the project **Connect** panel](/dashboard/project/_?showConnect=true&connectTab=frameworks&framework=tanstack).
<Button variant="primary" asChild>
- <a href="/dashboard/project/_?showConnect=true">Open Connect panel</a>
+ <a href="/dashboard/project/_?showConnect=true&connectTab=frameworks&framework=tanstack">
+ Open Connect panel
+ </a>
</Button>
-```text name=.env
+```text name=.env.local
VITE_SUPABASE_URL=<SUBSTITUTE_SUPABASE_URL>
VITE_SUPABASE_PUBLISHABLE_KEY=<SUBSTITUTE_SUPABASE_PUBLISHABLE_KEY>
```
-<$Partial path="api_settings.mdx" variables={{ "framework": "", "tab": "" }} />
+<$Partial path="api_settings.mdx" variables={{ "framework": "tanstack", "tab": "frameworks" }} />
-## 7. Create a Supabase client utility
+## 7. Create Supabase client utilities
-Create a new file at `src/utils/supabase.ts` to initialize the Supabase client.
+TanStack Start needs two Supabase clients: a browser client for components that run in the browser, and a server client for loaders and server functions. Create a `src/lib/supabase` folder with a file for each client.
-```ts name=src/utils/supabase.ts
-import { createClient } from '@supabase/supabase-js'
+```ts name=src/lib/supabase/client.ts
+/// <reference types="vite/types/importMeta.d.ts" />
+import { createBrowserClient } from '@supabase/ssr'
-export const supabase = createClient(
- import.meta.env.VITE_SUPABASE_URL,
- import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
-)
+export function createClient() {
+ return createBrowserClient(
+ import.meta.env.VITE_SUPABASE_URL!,
+ import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY!
+ )
+}
+```
+
+```ts name=src/lib/supabase/server.ts
+import { createServerClient } from '@supabase/ssr'
+import { getCookies, setCookie, setResponseHeader } from '@tanstack/react-start/server'
+
+export function createClient() {
+ return createServerClient(
+ process.env.VITE_SUPABASE_URL!,
+ process.env.VITE_SUPABASE_PUBLISHABLE_KEY!,
+ {
+ cookies: {
+ getAll() {
+ return Object.entries(getCookies()).map(([name, value]) => ({ name, value }))
+ },
+ setAll(cookies, headers) {
+ cookies.forEach(({ name, value, options }) => {
+ setCookie(name, value, options)
+ })
+
+ Object.entries(headers).forEach(([name, value]) => {
+ setResponseHeader(name, value)
+ })
+ },
+ },
+ }
+ )
+}
```
-## 8. Query data from the app
+## 8. Query Supabase data from TanStack Start
-Replace the contents of `src/routes/index.tsx` with the following code to add a loader function that fetches the instruments data and displays it on the page.
+Replace the contents of `src/routes/index.tsx` with the following to add a loader that queries the `instruments` table through the server client. The loader runs on the server, so the data is part of the initial server-rendered response.
```tsx name=src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'
-import { supabase } from '../utils/supabase'
+import { createClient } from '@/lib/supabase/server'
export const Route = createFileRoute('/')({
loader: async () => {
+ const supabase = createClient()
const { data: instruments } = await supabase.from('instruments').select()
return { instruments }
},
@@ -102,7 +134,8 @@ npm run dev
## Next steps
+- Learn how to [protect routes and check sessions](/docs/guides/auth/server-side/creating-a-client?queryGroups=framework&framework=tanstack) with the server client
+- Set up a complete [login and sign-up flow](/ui/docs/tanstack/password-based-auth) from the Supabase UI Library
- Explore [drop-in UI components](/ui) for your Supabase app
-- Set up [Auth](/docs/guides/auth) for your app
- [Insert more data](/docs/guides/database/import-data) into your database
- Upload and serve static files using [Storage](/docs/guides/storage)
diff --git a/examples/auth/tanstack/lib/supabase/client.ts b/examples/auth/tanstack/lib/supabase/client.ts
new file mode 100644
index 00000000000..3f34921e9f6
--- /dev/null
+++ b/examples/auth/tanstack/lib/supabase/client.ts
@@ -0,0 +1,9 @@
+/// <reference types="vite/types/importMeta.d.ts" />
+import { createBrowserClient } from '@supabase/ssr'
+
+export function createClient() {
+ return createBrowserClient(
+ import.meta.env.VITE_SUPABASE_URL!,
+ import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY!
+ )
+}
diff --git a/examples/auth/tanstack/lib/supabase/fetch-claims-server-fn.ts b/examples/auth/tanstack/lib/supabase/fetch-claims-server-fn.ts
new file mode 100644
index 00000000000..69e151984e6
--- /dev/null
+++ b/examples/auth/tanstack/lib/supabase/fetch-claims-server-fn.ts
@@ -0,0 +1,14 @@
+import { createServerFn } from '@tanstack/react-start'
+
+import { createClient } from '@/lib/supabase/server'
+
+export const fetchClaims = createServerFn({ method: 'GET' }).handler(async () => {
+ const supabase = createClient()
+ const { data, error } = await supabase.auth.getClaims()
+
+ if (error) {
+ return null
+ }
+
+ return data.claims
+})
diff --git a/examples/auth/tanstack/lib/supabase/server.ts b/examples/auth/tanstack/lib/supabase/server.ts
new file mode 100644
index 00000000000..04ce35c6a28
--- /dev/null
+++ b/examples/auth/tanstack/lib/supabase/server.ts
@@ -0,0 +1,31 @@
+import { createServerClient } from '@supabase/ssr'
+import { getCookies, setCookie, setResponseHeader } from '@tanstack/react-start/server'
+
+export function createClient() {
+ return createServerClient(
+ process.env.VITE_SUPABASE_URL!,
+ process.env.VITE_SUPABASE_PUBLISHABLE_KEY!,
+ {
+ cookies: {
+ getAll() {
+ return Object.entries(getCookies()).map(
+ ([name, value]) =>
+ ({
+ name,
+ value,
+ }) as { name: string; value: string }
+ )
+ },
+ setAll(cookies, headers) {
+ cookies.forEach(({ name, value, options }) => {
+ setCookie(name, value, options)
+ })
+
+ Object.entries(headers).forEach(([name, value]) => {
+ setResponseHeader(name, value)
+ })
+ },
+ },
+ }
+ )
+}
diff --git a/examples/auth/tanstack/routes/_protected.tsx b/examples/auth/tanstack/routes/_protected.tsx
new file mode 100644
index 00000000000..7ce91c49366
--- /dev/null
+++ b/examples/auth/tanstack/routes/_protected.tsx
@@ -0,0 +1,17 @@
+import { createFileRoute, redirect } from '@tanstack/react-router'
+
+import { fetchClaims } from '@/lib/supabase/fetch-claims-server-fn'
+
+export const Route = createFileRoute('/_protected')({
+ beforeLoad: async () => {
+ const claims = await fetchClaims()
+
+ if (!claims) {
+ throw redirect({ to: '/login' })
+ }
+
+ return {
+ claims,
+ }
+ },
+})