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.