docs(reference): add @supabase/ssr API reference

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',

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',

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',

apps/docs/docs/ref/ssr/installing.mdx

@@ -0,0 +1,55 @@
+---
+id: installing
+title: Installing
+slug: installing
+---
+
+### Install as a package
+
+<RefSubLayout.EducationRow>
+  <RefSubLayout.Details>
+
+    Install `@supabase/ssr` via your package manager. It has `@supabase/supabase-js` as a peer dependency, so install both.
+
+  </RefSubLayout.Details>
+
+  <RefSubLayout.Examples>
+
+    <Tabs
+      size="small"
+      type="underlined"
+      defaultActiveId="npm"
+      queryGroup="platform"
+    >
+      <TabPanel id="npm" label="npm">
+
+        ```sh Terminal
+        npm install @supabase/ssr @supabase/supabase-js
+        ```
+
+      </TabPanel>
+      <TabPanel id="yarn" label="Yarn">
+
+        ```sh Terminal
+        yarn add @supabase/ssr @supabase/supabase-js
+        ```
+
+      </TabPanel>
+      <TabPanel id="pnpm" label="pnpm">
+
+        ```sh Terminal
+        pnpm add @supabase/ssr @supabase/supabase-js
+        ```
+
+      </TabPanel>
+      <TabPanel id="bun" label="Bun">
+
+        ```sh Terminal
+        bun add @supabase/ssr @supabase/supabase-js
+        ```
+
+      </TabPanel>
+    </Tabs>
+
+  </RefSubLayout.Examples>
+</RefSubLayout.EducationRow>

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).

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',
+])

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',

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',

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",

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
 

apps/docs/spec/reference/ssr/v1/config.json

@@ -0,0 +1,5 @@
+{
+  "categoryOrder": ["Clients", "Cookies", "Types", "Deprecated"],
+  "partialsOrder": ["introduction", "installing"],
+  "navigationPrefixes": {}
+}

apps/docs/spec/reference/ssr/v1/partials/installing.mdx

@@ -0,0 +1,55 @@
+---
+id: installing
+title: Installing
+slug: installing
+---
+
+### Install as a package
+
+<RefSubLayout.EducationRow>
+  <RefSubLayout.Details>
+
+    Install `@supabase/ssr` via your package manager. It has `@supabase/supabase-js` as a peer dependency, so install both.
+
+  </RefSubLayout.Details>
+
+  <RefSubLayout.Examples>
+
+    <Tabs
+      size="small"
+      type="underlined"
+      defaultActiveId="npm"
+      queryGroup="platform"
+    >
+      <TabPanel id="npm" label="npm">
+
+        ```sh Terminal
+        npm install @supabase/ssr @supabase/supabase-js
+        ```
+
+      </TabPanel>
+      <TabPanel id="yarn" label="Yarn">
+
+        ```sh Terminal
+        yarn add @supabase/ssr @supabase/supabase-js
+        ```
+
+      </TabPanel>
+      <TabPanel id="pnpm" label="pnpm">
+
+        ```sh Terminal
+        pnpm add @supabase/ssr @supabase/supabase-js
+        ```
+
+      </TabPanel>
+      <TabPanel id="bun" label="Bun">
+
+        ```sh Terminal
+        bun add @supabase/ssr @supabase/supabase-js
+        ```
+
+      </TabPanel>
+    </Tabs>
+
+  </RefSubLayout.Examples>
+</RefSubLayout.EducationRow>

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).

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 },
   ]

apps/www/app/llms.txt/route.ts

@@ -68,6 +68,7 @@ async function getSources(): Promise<Source[]> {
     { 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 },
   ]