From f77e8e75b63d4dd2e5168853076467ddb7041552 Mon Sep 17 00:00:00 2001 From: Katerina Skroumpelou Date: Tue, 7 Jul 2026 17:08:51 +0300 Subject: [PATCH] docs: wire @supabase/server v1 into the reference pipeline (#47570) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. * https://docs-git-docs-wire-server-v1-reference-supabase.vercel.app/docs/reference/server/introduction * Screenshot 2026-07-06 at 6 13 33 PM ## What is the current behavior? `@supabase/server` has no reference documentation page in the Supabase docs. The library publishes a TypeDoc spec to GitHub Pages but the docs pipeline was not wired up to consume it. ## What is the new behavior? - Adds `spec/reference/server/v1/` with a `config.json` (category order: Middleware, Primitives, Adapters, Errors, Types) and `partials/` for the introduction and installing pages. - Adds a `download.server.v1` Makefile target that fetches `https://supabase.github.io/server/spec.json` into `spec/reference/server/v1/server.json`, and wires it into the top-level `download` target so it runs with the rest. - Registers `server-v1` in `SUPPORTS_NEW_REFERENCE_PROCESS` so the build pipeline picks up the new spec directory and generates `content/reference/server/v1/` at build time. - Seeds the generated `docs/ref/server/` partials (introduction and installing) that the reference router serves. ## Additional context The TypeDoc spec is produced by `@supabase/server`'s `docs.yml` workflow on every push to `main`, so `make download.server.v1` will always pull the latest published API surface. The companion PR in the server repo ([supabase/server#95](https://github.com/supabase/server/pull/95)) adds the `@category` tags that the pipeline requires for symbols to appear in navigation. ## Summary by CodeRabbit * **New Features** * Added a new **Server SDK** item under **Reference**, linking to `/reference/server` and marked with a **New** badge. * Published **Server Reference v1** documentation for `@supabase/server`, including **Introduction** and **Installing** pages. * **Chores / Improvements** * Enhanced the reference documentation generation to include Server v1 content. * Improved reference detail handling (including clearer TypeDoc output such as **Deprecated** notes). --------- Co-authored-by: Chris Chinchilla --- .../components/Navigation/Navigation.types.ts | 1 + .../NavigationMenu/GlobalMobileMenu.tsx | 1 + .../NavigationMenu/GlobalNavigationMenu.tsx | 5 +- .../NavigationMenu.constants.ts | 18 ++++ .../NavigationMenu/NavigationMenu.tsx | 6 ++ apps/docs/content/navigation.references.ts | 14 ++++ apps/docs/docs/ref/server/installing.mdx | 84 +++++++++++++++++++ apps/docs/docs/ref/server/introduction.mdx | 8 ++ .../docs/features/docs/Reference.constants.ts | 2 +- apps/docs/features/docs/Reference.typeSpec.ts | 20 +++++ apps/docs/layouts/MainSkeleton.tsx | 4 + apps/docs/package.json | 4 +- apps/docs/scripts/build-reference-content.ts | 50 +++++++++++ apps/docs/spec/Makefile | 7 +- .../docs/spec/reference/server/v1/config.json | 5 ++ .../server/v1/partials/installing.mdx | 84 +++++++++++++++++++ .../server/v1/partials/introduction.mdx | 8 ++ 17 files changed, 316 insertions(+), 5 deletions(-) create mode 100644 apps/docs/docs/ref/server/installing.mdx create mode 100644 apps/docs/docs/ref/server/introduction.mdx create mode 100644 apps/docs/spec/reference/server/v1/config.json create mode 100644 apps/docs/spec/reference/server/v1/partials/installing.mdx create mode 100644 apps/docs/spec/reference/server/v1/partials/introduction.mdx diff --git a/apps/docs/components/Navigation/Navigation.types.ts b/apps/docs/components/Navigation/Navigation.types.ts index b786a96586e..9dfc85e6142 100644 --- a/apps/docs/components/Navigation/Navigation.types.ts +++ b/apps/docs/components/Navigation/Navigation.types.ts @@ -24,6 +24,7 @@ type MenuItem = { level?: string hasLightIcon?: boolean community?: boolean + new?: boolean enabled?: boolean } diff --git a/apps/docs/components/Navigation/NavigationMenu/GlobalMobileMenu.tsx b/apps/docs/components/Navigation/NavigationMenu/GlobalMobileMenu.tsx index 7c9fb2c367a..e08325e5538 100644 --- a/apps/docs/components/Navigation/NavigationMenu/GlobalMobileMenu.tsx +++ b/apps/docs/components/Navigation/NavigationMenu/GlobalMobileMenu.tsx @@ -63,6 +63,7 @@ const AccordionMenuItem = ({ section }: { section: DropdownMenuItem[] }) => { href={item.href} title={item.label} community={item.community} + new={item.new} icon={item.icon} /> ) diff --git a/apps/docs/components/Navigation/NavigationMenu/GlobalNavigationMenu.tsx b/apps/docs/components/Navigation/NavigationMenu/GlobalNavigationMenu.tsx index eef11e60607..3b6c71ed599 100644 --- a/apps/docs/components/Navigation/NavigationMenu/GlobalNavigationMenu.tsx +++ b/apps/docs/components/Navigation/NavigationMenu/GlobalNavigationMenu.tsx @@ -117,6 +117,7 @@ const GlobalNavigationMenu: FC = () => { href={item.href} title={item.label} community={item.community} + new={item.new} icon={item.icon} /> @@ -162,8 +163,9 @@ export const MenuItem = React.forwardRef< React.ComponentPropsWithoutRef<'a'> & { icon?: string community?: boolean + new?: boolean } ->(({ className, title, href = '', icon, community, children, ...props }, ref) => { +>(({ className, title, href = '', icon, community, new: isNew, children, ...props }, ref) => { return ( } {title} {community && Community} + {isNew && New} )} diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index aa171e3742c..d6699ade685 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -280,6 +280,13 @@ export const GLOBAL_MENU_ITEMS: GlobalMenuItems = [ }, ], [ + { + label: 'Server SDK', + icon: 'reference-javascript', + href: '/reference/server' as `/${string}`, + level: 'reference_server', + new: true, + }, { label: 'CLI Commands', icon: 'reference-cli', @@ -3348,6 +3355,17 @@ export const reference_javascript_v2 = { }, } +export const reference_server_v1 = { + icon: 'reference-javascript', + title: 'Server', + url: '/reference/server', + parent: '/reference', + pkg: { + name: '@supabase/server', + repo: 'https://github.com/supabase/server', + }, +} + // 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 5b51b704c83..73bcfdc175c 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx @@ -27,6 +27,7 @@ enum MenuId { AiTools = 'ai_tools', LocalDevelopment = 'local_development', Contributing = 'contributing', + RefServerV1 = 'reference_server_v1', RefJavaScriptV1 = 'reference_javascript_v1', RefJavaScriptV2 = 'reference_javascript_v2', RefDartV1 = 'reference_dart_v1', @@ -147,6 +148,11 @@ const menus: Menu[] = [ id: MenuId.Deployment, type: 'guide', }, + { + id: MenuId.RefServerV1, + type: 'reference', + path: '/reference/server', + }, { id: MenuId.RefJavaScriptV1, type: 'reference', diff --git a/apps/docs/content/navigation.references.ts b/apps/docs/content/navigation.references.ts index b1a1fc10972..92c56d6b60c 100644 --- a/apps/docs/content/navigation.references.ts +++ b/apps/docs/content/navigation.references.ts @@ -30,6 +30,20 @@ export const REFERENCES = { }, }, }, + server: { + type: 'sdk', + name: 'Server', + library: '@supabase/server', + libPath: 'server', + versions: ['v1'], + typeSpec: true, + icon: 'reference-javascript', + meta: { + v1: { + libId: 'reference_server_v1', + }, + }, + }, dart: { type: 'sdk', name: 'Flutter', diff --git a/apps/docs/docs/ref/server/installing.mdx b/apps/docs/docs/ref/server/installing.mdx new file mode 100644 index 00000000000..0f0df8a9b91 --- /dev/null +++ b/apps/docs/docs/ref/server/installing.mdx @@ -0,0 +1,84 @@ +--- +id: installing +title: Installing +slug: installing +--- + +### Install as a package + + + + + Install `@supabase/server` via your package manager. + + + + + + + + + ```sh Terminal + npm install @supabase/server + ``` + + + + + ```sh Terminal + yarn add @supabase/server + ``` + + + + + ```sh Terminal + pnpm add @supabase/server + ``` + + + + + + + +### Use via JSR (Deno / Bun) + + + + + `@supabase/server` is also published to [JSR](https://jsr.io/@supabase/server) for Deno and Bun environments. + + + + + + + + + ```sh Terminal + deno add jsr:@supabase/server + ``` + + + + + ```sh Terminal + bunx jsr add @supabase/server + ``` + + + + + + diff --git a/apps/docs/docs/ref/server/introduction.mdx b/apps/docs/docs/ref/server/introduction.mdx new file mode 100644 index 00000000000..eaacb0c51dd --- /dev/null +++ b/apps/docs/docs/ref/server/introduction.mdx @@ -0,0 +1,8 @@ +--- +id: introduction +title: Introduction +--- + +`@supabase/server` is a framework-agnostic library for authenticating requests in server-side JavaScript environments. It verifies JWTs, resolves Supabase API keys, and creates pre-configured Supabase clients — exposing everything through a single `SupabaseContext` that is identical regardless of which adapter or primitive produced it. + +Adapters for Hono, H3, Elysia, and NestJS are included. You can also compose the lower-level primitives directly for custom frameworks or edge runtimes. diff --git a/apps/docs/features/docs/Reference.constants.ts b/apps/docs/features/docs/Reference.constants.ts index 71daf6b8fe1..ec3e861fb90 100644 --- a/apps/docs/features/docs/Reference.constants.ts +++ b/apps/docs/features/docs/Reference.constants.ts @@ -16,4 +16,4 @@ * not listed here keeps reading from the legacy `features/docs/generated/` * outputs. */ -export const SUPPORTS_NEW_REFERENCE_PROCESS = new Set(['javascript-v2', 'dart-v2']) +export const SUPPORTS_NEW_REFERENCE_PROCESS = new Set(['javascript-v2', 'dart-v2', 'server-v1']) diff --git a/apps/docs/features/docs/Reference.typeSpec.ts b/apps/docs/features/docs/Reference.typeSpec.ts index 9bd84b6f56e..0c8e389e77b 100644 --- a/apps/docs/features/docs/Reference.typeSpec.ts +++ b/apps/docs/features/docs/Reference.typeSpec.ts @@ -186,6 +186,7 @@ export const KIND_CONSTRUCTOR = 512 export const KIND_PROPERTY = 1024 export const KIND_METHOD = 2048 export const KIND_TYPE_LITERAL = 65536 +export const KIND_TYPE_ALIAS = 2097152 /** * @@ -259,6 +260,25 @@ export function normalizeComment( } } + // Surface @deprecated so deprecated-only symbols (e.g. type aliases whose + // only doc content is a @deprecated tag) still render a description instead + // of an empty card. Inline {@link X} parts fall back to their text. Angle + // brackets are HTML-escaped because the note is rendered via MDX, which would + // otherwise parse a generic like `overrideTypes` as a JSX tag and throw. + if ('blockTags' in original && Array.isArray(original.blockTags)) { + const deprecatedTag = original.blockTags.find((t) => t.tag === '@deprecated') + if (deprecatedTag) { + const detail = deprecatedTag.content + .map((p) => p.text) + .join('') + .trim() + .replace(//g, '>') + const note = detail ? `**Deprecated.** ${detail}` : '**Deprecated.**' + comment.text = comment.text ? `${note}\n\n${comment.text}` : note + } + } + // Extract @example tags from blockTags if ('blockTags' in original && Array.isArray(original.blockTags)) { const exampleTags = original.blockTags.filter((t) => t.tag === '@example') diff --git a/apps/docs/layouts/MainSkeleton.tsx b/apps/docs/layouts/MainSkeleton.tsx index 048bed82157..7a1c841759c 100644 --- a/apps/docs/layouts/MainSkeleton.tsx +++ b/apps/docs/layouts/MainSkeleton.tsx @@ -105,6 +105,10 @@ const levelsData = { icon: 'integrations', name: 'Integrations', }, + reference_server_v1: { + icon: 'reference-javascript', + name: 'Server 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 c82cd4ca9f1..c4388bfc3c4 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -15,10 +15,10 @@ "clean": "rimraf .next .turbo node_modules features/docs/generated examples __generated__", "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)", + "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:dart": "tsx scripts/generate-dart-reference.ts", "precodegen:references:new": "pnpm run codegen:references:new:ensure && pnpm run codegen:references:dart", - "codegen:references:new": "tsx scripts/build-reference-content.ts", + "codegen:references:new": "pnpm run codegen:references:new:ensure && tsx scripts/build-reference-content.ts", "codegen:references:legacy": "tsx features/docs/Reference.generated.script.ts", "codegen:references": "pnpm codegen:references:legacy && pnpm codegen:references:new", "codemod:frontmatter": "node ./scripts/codemod/mdx-meta.mjs && prettier --cache --write \"content/**/*.mdx\"", diff --git a/apps/docs/scripts/build-reference-content.ts b/apps/docs/scripts/build-reference-content.ts index 6c2c37e6880..eca936d097a 100644 --- a/apps/docs/scripts/build-reference-content.ts +++ b/apps/docs/scripts/build-reference-content.ts @@ -18,6 +18,10 @@ import matter from 'gray-matter' import { buildMap, + KIND_CLASS, + KIND_INTERFACE, + KIND_PROPERTY, + KIND_TYPE_ALIAS, KIND_VARIABLE, normalizeComment, parseSignature, @@ -365,6 +369,52 @@ function collectFunctions( isConst: node.flags?.isConst ?? false, } out.typeSpec.variables[ref] = variableEntry + } else if (node.kind === KIND_TYPE_ALIAS && node.type) { + // Type alias — store description and underlying type definition + const variableEntry: VariableTypes = { + name: ref, + type: parseType(node.type, idMap), + comment: node.comment ? normalizeComment(node.comment as any) : undefined, + isConst: false, + } + out.typeSpec.variables[ref] = variableEntry + } else if (node.kind === KIND_INTERFACE && node.children) { + // Interface — store as a method-like entry so the renderer shows properties as a param table + const params = (node.children as any[]) + .filter((child: any) => child.kind === KIND_PROPERTY) + .map((prop: any) => ({ + name: prop.name, + comment: prop.comment ? normalizeComment(prop.comment as any) : undefined, + isOptional: prop.flags?.isOptional ?? false, + type: prop.type ? parseType(prop.type, idMap) : undefined, + })) + const methodEntry: MethodTypes = { + name: ref, + params, + ret: undefined, + comment: node.comment ? normalizeComment(node.comment as any) : undefined, + } + out.typeSpec.methods[ref] = methodEntry + } else if (node.kind === KIND_CLASS && node.children) { + // Class — store as a method-like entry so the renderer shows the class + // description plus its public properties as a param table. Without this, + // classes fall through every branch and only their constructor child is + // stored, leaving the class ref (which functions.json points at) empty. + const params = (node.children as any[]) + .filter((child: any) => child.kind === KIND_PROPERTY) + .map((prop: any) => ({ + name: prop.name, + comment: prop.comment ? normalizeComment(prop.comment as any) : undefined, + isOptional: prop.flags?.isOptional ?? false, + type: prop.type ? parseType(prop.type, idMap) : undefined, + })) + const methodEntry: MethodTypes = { + name: ref, + params, + ret: undefined, + comment: node.comment ? normalizeComment(node.comment as any) : undefined, + } + out.typeSpec.methods[ref] = methodEntry } } diff --git a/apps/docs/spec/Makefile b/apps/docs/spec/Makefile index c7e125bffa4..205cdd3d6e6 100644 --- a/apps/docs/spec/Makefile +++ b/apps/docs/spec/Makefile @@ -1,6 +1,8 @@ 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 + run: download transform generate format @@ -9,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: download.api.v1 download.storage.v1 download.tsdoc.v2 download.server.v1 download.api.v1: curl -sS https://api.supabase.com/api/v1-json > $(REPO_DIR)/api_v1_openapi.json @@ -44,6 +46,9 @@ download.tsdoc.v2: curl -sS https://supabase.github.io/supabase-js/storage-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/storage.json curl -sS https://supabase.github.io/supabase-js/functions-js/v2/spec.json > $(REPO_DIR)/reference/javascript/v2/functions.json +download.server.v1: + curl -sSf https://supabase.github.io/server/spec.json > $(REPO_DIR)/reference/server/v1/server.json + download.analytics.v0: curl -sS https://logflare.app/api/openapi > $(REPO_DIR)/analytics_v0_openapi.json diff --git a/apps/docs/spec/reference/server/v1/config.json b/apps/docs/spec/reference/server/v1/config.json new file mode 100644 index 00000000000..dc086ebe58f --- /dev/null +++ b/apps/docs/spec/reference/server/v1/config.json @@ -0,0 +1,5 @@ +{ + "categoryOrder": ["Middleware", "Primitives", "Adapters", "Errors", "Types"], + "partialsOrder": ["introduction", "installing"], + "navigationPrefixes": {} +} diff --git a/apps/docs/spec/reference/server/v1/partials/installing.mdx b/apps/docs/spec/reference/server/v1/partials/installing.mdx new file mode 100644 index 00000000000..0f0df8a9b91 --- /dev/null +++ b/apps/docs/spec/reference/server/v1/partials/installing.mdx @@ -0,0 +1,84 @@ +--- +id: installing +title: Installing +slug: installing +--- + +### Install as a package + + + + + Install `@supabase/server` via your package manager. + + + + + + + + + ```sh Terminal + npm install @supabase/server + ``` + + + + + ```sh Terminal + yarn add @supabase/server + ``` + + + + + ```sh Terminal + pnpm add @supabase/server + ``` + + + + + + + +### Use via JSR (Deno / Bun) + + + + + `@supabase/server` is also published to [JSR](https://jsr.io/@supabase/server) for Deno and Bun environments. + + + + + + + + + ```sh Terminal + deno add jsr:@supabase/server + ``` + + + + + ```sh Terminal + bunx jsr add @supabase/server + ``` + + + + + + diff --git a/apps/docs/spec/reference/server/v1/partials/introduction.mdx b/apps/docs/spec/reference/server/v1/partials/introduction.mdx new file mode 100644 index 00000000000..eaacb0c51dd --- /dev/null +++ b/apps/docs/spec/reference/server/v1/partials/introduction.mdx @@ -0,0 +1,8 @@ +--- +id: introduction +title: Introduction +--- + +`@supabase/server` is a framework-agnostic library for authenticating requests in server-side JavaScript environments. It verifies JWTs, resolves Supabase API keys, and creates pre-configured Supabase clients — exposing everything through a single `SupabaseContext` that is identical regardless of which adapter or primitive produced it. + +Adapters for Hono, H3, Elysia, and NestJS are included. You can also compose the lower-level primitives directly for custom frameworks or edge runtimes.