From edafa1c1fc0faff61373e15cf59777e8a1c4258b Mon Sep 17 00:00:00 2001 From: Katerina Skroumpelou Date: Thu, 16 Jul 2026 15:19:51 +0300 Subject: [PATCH] docs(reference): add @supabase/ssr API reference --- .../NavigationMenu.constants.ts | 18 ++++++ .../NavigationMenu/NavigationMenu.tsx | 6 ++ apps/docs/content/navigation.references.ts | 17 ++++++ apps/docs/docs/ref/ssr/installing.mdx | 55 +++++++++++++++++++ apps/docs/docs/ref/ssr/introduction.mdx | 10 ++++ .../docs/features/docs/Reference.constants.ts | 7 ++- .../internals/generate-reference-markdown.ts | 7 +++ apps/docs/layouts/MainSkeleton.tsx | 4 ++ apps/docs/package.json | 2 +- apps/docs/spec/Makefile | 7 ++- apps/docs/spec/reference/ssr/v1/config.json | 5 ++ .../reference/ssr/v1/partials/installing.mdx | 55 +++++++++++++++++++ .../ssr/v1/partials/introduction.mdx | 10 ++++ apps/www/app/llms-full.txt/route.ts | 1 + apps/www/app/llms.txt/route.ts | 1 + 15 files changed, 201 insertions(+), 4 deletions(-) create mode 100644 apps/docs/docs/ref/ssr/installing.mdx create mode 100644 apps/docs/docs/ref/ssr/introduction.mdx create mode 100644 apps/docs/spec/reference/ssr/v1/config.json create mode 100644 apps/docs/spec/reference/ssr/v1/partials/installing.mdx create mode 100644 apps/docs/spec/reference/ssr/v1/partials/introduction.mdx diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index 1f16c321f64..7f9fdea0683 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -287,6 +287,13 @@ export const GLOBAL_MENU_ITEMS: GlobalMenuItems = [ level: 'reference_server', new: true, }, + { + label: 'SSR', + icon: 'reference-javascript', + href: '/reference/ssr' as `/${string}`, + level: 'reference_ssr', + new: true, + }, { label: 'CLI Commands', icon: 'reference-cli', @@ -3381,6 +3388,17 @@ export const reference_server_v1 = { }, } +export const reference_ssr_v1 = { + icon: 'reference-javascript', + title: 'SSR', + url: '/reference/ssr', + parent: '/reference', + pkg: { + name: '@supabase/ssr', + repo: 'https://github.com/supabase/ssr', + }, +} + // TODO: How to? export const reference_dart_v1 = { icon: 'reference-dart', diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx index 73bcfdc175c..d2361d4324f 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx @@ -28,6 +28,7 @@ enum MenuId { LocalDevelopment = 'local_development', Contributing = 'contributing', RefServerV1 = 'reference_server_v1', + RefSsrV1 = 'reference_ssr_v1', RefJavaScriptV1 = 'reference_javascript_v1', RefJavaScriptV2 = 'reference_javascript_v2', RefDartV1 = 'reference_dart_v1', @@ -153,6 +154,11 @@ const menus: Menu[] = [ type: 'reference', path: '/reference/server', }, + { + id: MenuId.RefSsrV1, + type: 'reference', + path: '/reference/ssr', + }, { id: MenuId.RefJavaScriptV1, type: 'reference', diff --git a/apps/docs/content/navigation.references.ts b/apps/docs/content/navigation.references.ts index 92c56d6b60c..e4307178f35 100644 --- a/apps/docs/content/navigation.references.ts +++ b/apps/docs/content/navigation.references.ts @@ -44,6 +44,23 @@ export const REFERENCES = { }, }, }, + ssr: { + type: 'sdk', + name: 'SSR', + library: '@supabase/ssr', + libPath: 'ssr', + versions: ['v1'], + typeSpec: true, + icon: 'reference-javascript', + meta: { + v1: { + // SSR is driven by the new reference pipeline + // (`scripts/build-reference-content.ts` + `spec/reference/ssr/v1/`). + // It intentionally has no `specFile` — the legacy YAML loader skips it. + libId: 'reference_ssr_v1', + }, + }, + }, dart: { type: 'sdk', name: 'Flutter', diff --git a/apps/docs/docs/ref/ssr/installing.mdx b/apps/docs/docs/ref/ssr/installing.mdx new file mode 100644 index 00000000000..3042f709772 --- /dev/null +++ b/apps/docs/docs/ref/ssr/installing.mdx @@ -0,0 +1,55 @@ +--- +id: installing +title: Installing +slug: installing +--- + +### Install as a package + + + + + Install `@supabase/ssr` via your package manager. It has `@supabase/supabase-js` as a peer dependency, so install both. + + + + + + + + + ```sh Terminal + npm install @supabase/ssr @supabase/supabase-js + ``` + + + + + ```sh Terminal + yarn add @supabase/ssr @supabase/supabase-js + ``` + + + + + ```sh Terminal + pnpm add @supabase/ssr @supabase/supabase-js + ``` + + + + + ```sh Terminal + bun add @supabase/ssr @supabase/supabase-js + ``` + + + + + + diff --git a/apps/docs/docs/ref/ssr/introduction.mdx b/apps/docs/docs/ref/ssr/introduction.mdx new file mode 100644 index 00000000000..7452db6ac20 --- /dev/null +++ b/apps/docs/docs/ref/ssr/introduction.mdx @@ -0,0 +1,10 @@ +--- +id: introduction +title: Introduction +--- + +`@supabase/ssr` lets you use Supabase in server-side rendering (SSR) frameworks by persisting the user's session in cookies instead of browser local storage. Cookies are sent with every request, so the server can read and refresh the session while rendering. + +It exposes two client factories — `createBrowserClient` for the browser and `createServerClient` for the server — that share the same cookie-based storage, plus the cookie helper types you need to wire them into your framework. It replaces the deprecated `@supabase/auth-helpers-*` packages. + +For end-to-end setup in Next.js, Remix, SvelteKit, and other frameworks, see the [server-side rendering guides](/docs/guides/auth/server-side). If you need token-based authentication for backend APIs and edge runtimes rather than cookie-based sessions, see [which package to use](/docs/guides/auth/choosing-a-server-package) and [`@supabase/server`](/docs/reference/server). diff --git a/apps/docs/features/docs/Reference.constants.ts b/apps/docs/features/docs/Reference.constants.ts index ec3e861fb90..ec0570ca85a 100644 --- a/apps/docs/features/docs/Reference.constants.ts +++ b/apps/docs/features/docs/Reference.constants.ts @@ -16,4 +16,9 @@ * not listed here keeps reading from the legacy `features/docs/generated/` * outputs. */ -export const SUPPORTS_NEW_REFERENCE_PROCESS = new Set(['javascript-v2', 'dart-v2', 'server-v1']) +export const SUPPORTS_NEW_REFERENCE_PROCESS = new Set([ + 'javascript-v2', + 'dart-v2', + 'server-v1', + 'ssr-v1', +]) diff --git a/apps/docs/internals/generate-reference-markdown.ts b/apps/docs/internals/generate-reference-markdown.ts index 8f18dabc286..64e15ef5aa8 100644 --- a/apps/docs/internals/generate-reference-markdown.ts +++ b/apps/docs/internals/generate-reference-markdown.ts @@ -116,6 +116,13 @@ const REFERENCES: Ref[] = [ mdxDir: path.join(MDX_ROOT, 'server'), contentDir: path.join(process.cwd(), 'content/reference/server/v1'), }, + { + kind: 'sdk-new', + title: 'Supabase SSR Reference', + outFile: 'ssr.md', + mdxDir: path.join(MDX_ROOT, 'ssr'), + contentDir: path.join(process.cwd(), 'content/reference/ssr/v1'), + }, { kind: 'sdk-legacy', title: 'Kotlin Client Library Reference', diff --git a/apps/docs/layouts/MainSkeleton.tsx b/apps/docs/layouts/MainSkeleton.tsx index 7a1c841759c..d4e2ea0d696 100644 --- a/apps/docs/layouts/MainSkeleton.tsx +++ b/apps/docs/layouts/MainSkeleton.tsx @@ -109,6 +109,10 @@ const levelsData = { icon: 'reference-javascript', name: 'Server Reference v1.0', }, + reference_ssr_v1: { + icon: 'reference-javascript', + name: 'SSR Reference v1.0', + }, reference_javascript_v1: { icon: 'reference-javascript', name: 'JavaScript Reference v1.0', diff --git a/apps/docs/package.json b/apps/docs/package.json index 87f158579da..a63d1f744c8 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -16,7 +16,7 @@ "clean": "rimraf .next .turbo features/docs/generated examples __generated__ tsconfig.tsbuildinfo", "codegen:examples": "shx cp -r ../../examples ./examples", "codegen:graphql": "tsx --conditions=react-server ./scripts/graphqlSchema.ts && graphql-codegen --config codegen.ts", - "codegen:references:new:ensure": "(test -f spec/reference/javascript/v2/supabase.json || (cd spec && make download.tsdoc.v2)) && (test -f spec/reference/server/v1/server.json || (cd spec && make download.server.v1))", + "codegen:references:new:ensure": "(test -f spec/reference/javascript/v2/supabase.json || (cd spec && make download.tsdoc.v2)) && (test -f spec/reference/server/v1/server.json || (cd spec && make download.server.v1)) && (test -f spec/reference/ssr/v1/ssr.json || (cd spec && make download.ssr.v1))", "codegen:references:dart": "tsx scripts/generate-dart-reference.ts", "precodegen:references:new": "pnpm run codegen:references:new:ensure && pnpm run codegen:references:dart", "codegen:references:new": "pnpm run codegen:references:new:ensure && tsx scripts/build-reference-content.ts", diff --git a/apps/docs/spec/Makefile b/apps/docs/spec/Makefile index 205cdd3d6e6..daa5e820f48 100644 --- a/apps/docs/spec/Makefile +++ b/apps/docs/spec/Makefile @@ -1,7 +1,7 @@ REPO_DIR=$(shell pwd) GENERATOR_DIR=../../../packages/generator -.PHONY: run download download.api.v1 download.storage.v1 download.tsdoc.v2 download.server.v1 transform dereference.api.v1 dereference.auth.v1 dereference.storage.v0 generate generate.sections.api.v1 format +.PHONY: run download download.api.v1 download.storage.v1 download.tsdoc.v2 download.server.v1 download.ssr.v1 transform dereference.api.v1 dereference.auth.v1 dereference.storage.v0 generate generate.sections.api.v1 format run: download transform generate format @@ -11,7 +11,7 @@ run: download transform generate format ############################################################################### # comment out download.auth.v1 temporarily, we're manually creating the file # download: download.api.v1 download.auth.v1 download.storage.v1 download.tsdoc.v2 -download: download.api.v1 download.storage.v1 download.tsdoc.v2 download.server.v1 +download: download.api.v1 download.storage.v1 download.tsdoc.v2 download.server.v1 download.ssr.v1 download.api.v1: curl -sS https://api.supabase.com/api/v1-json > $(REPO_DIR)/api_v1_openapi.json @@ -49,6 +49,9 @@ download.tsdoc.v2: download.server.v1: curl -sSf https://supabase.github.io/server/spec.json > $(REPO_DIR)/reference/server/v1/server.json +download.ssr.v1: + curl -sSf https://supabase.github.io/ssr/spec.json > $(REPO_DIR)/reference/ssr/v1/ssr.json + download.analytics.v0: curl -sS https://logflare.app/api/openapi > $(REPO_DIR)/analytics_v0_openapi.json diff --git a/apps/docs/spec/reference/ssr/v1/config.json b/apps/docs/spec/reference/ssr/v1/config.json new file mode 100644 index 00000000000..9157338e79c --- /dev/null +++ b/apps/docs/spec/reference/ssr/v1/config.json @@ -0,0 +1,5 @@ +{ + "categoryOrder": ["Clients", "Cookies", "Types", "Deprecated"], + "partialsOrder": ["introduction", "installing"], + "navigationPrefixes": {} +} diff --git a/apps/docs/spec/reference/ssr/v1/partials/installing.mdx b/apps/docs/spec/reference/ssr/v1/partials/installing.mdx new file mode 100644 index 00000000000..3042f709772 --- /dev/null +++ b/apps/docs/spec/reference/ssr/v1/partials/installing.mdx @@ -0,0 +1,55 @@ +--- +id: installing +title: Installing +slug: installing +--- + +### Install as a package + + + + + Install `@supabase/ssr` via your package manager. It has `@supabase/supabase-js` as a peer dependency, so install both. + + + + + + + + + ```sh Terminal + npm install @supabase/ssr @supabase/supabase-js + ``` + + + + + ```sh Terminal + yarn add @supabase/ssr @supabase/supabase-js + ``` + + + + + ```sh Terminal + pnpm add @supabase/ssr @supabase/supabase-js + ``` + + + + + ```sh Terminal + bun add @supabase/ssr @supabase/supabase-js + ``` + + + + + + diff --git a/apps/docs/spec/reference/ssr/v1/partials/introduction.mdx b/apps/docs/spec/reference/ssr/v1/partials/introduction.mdx new file mode 100644 index 00000000000..7452db6ac20 --- /dev/null +++ b/apps/docs/spec/reference/ssr/v1/partials/introduction.mdx @@ -0,0 +1,10 @@ +--- +id: introduction +title: Introduction +--- + +`@supabase/ssr` lets you use Supabase in server-side rendering (SSR) frameworks by persisting the user's session in cookies instead of browser local storage. Cookies are sent with every request, so the server can read and refresh the session while rendering. + +It exposes two client factories — `createBrowserClient` for the browser and `createServerClient` for the server — that share the same cookie-based storage, plus the cookie helper types you need to wire them into your framework. It replaces the deprecated `@supabase/auth-helpers-*` packages. + +For end-to-end setup in Next.js, Remix, SvelteKit, and other frameworks, see the [server-side rendering guides](/docs/guides/auth/server-side). If you need token-based authentication for backend APIs and edge runtimes rather than cookie-based sessions, see [which package to use](/docs/guides/auth/choosing-a-server-package) and [`@supabase/server`](/docs/reference/server). diff --git a/apps/www/app/llms-full.txt/route.ts b/apps/www/app/llms-full.txt/route.ts index a243474bbe6..bf4e10fb5a6 100644 --- a/apps/www/app/llms-full.txt/route.ts +++ b/apps/www/app/llms-full.txt/route.ts @@ -37,6 +37,7 @@ function getSources(): Source[] { { title: 'Supabase Reference (Python)', slug: 'python', enabled: sdkPython }, { title: 'Supabase Reference (C#)', slug: 'csharp', enabled: sdkCsharp }, { title: 'Supabase Server SDK Reference', slug: 'server', enabled: true }, + { title: 'Supabase SSR Reference', slug: 'ssr', enabled: true }, { title: 'Supabase CLI Reference', slug: 'cli', enabled: true }, { title: 'Supabase Management API Reference', slug: 'api', enabled: true }, ] diff --git a/apps/www/app/llms.txt/route.ts b/apps/www/app/llms.txt/route.ts index 4c07a6d7fd8..e26563536f0 100644 --- a/apps/www/app/llms.txt/route.ts +++ b/apps/www/app/llms.txt/route.ts @@ -68,6 +68,7 @@ async function getSources(): Promise { { title: 'Supabase Reference (Python)', relPath: 'llms/python.txt', enabled: sdkPython }, { title: 'Supabase Reference (C#)', relPath: 'llms/csharp.txt', enabled: sdkCsharp }, { title: 'Supabase Server SDK Reference', relPath: 'llms/server.txt', enabled: true }, + { title: 'Supabase SSR Reference', relPath: 'llms/ssr.txt', enabled: true }, { title: 'Supabase CLI Reference', relPath: 'llms/cli.txt', enabled: true }, { title: 'Supabase Management API Reference', relPath: 'llms/api.txt', enabled: true }, ]