The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: wire middleware sdk docs (#49854)
Katerina Skroumpelou6e83f71a563a
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsindex 28501353fc0..2afa1d2bf35 100644--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts@@ -285,6 +285,13 @@ export const GLOBAL_MENU_ITEMS: GlobalMenuItems = [level: 'reference_server',new: true,},+ {+ label: 'Middleware SDK',+ icon: 'reference-javascript',+ href: '/reference/middleware' as `/${string}`,+ level: 'reference_middleware',+ new: true,+ },{label: 'CLI Commands',icon: 'reference-cli',@@ -3432,6 +3439,17 @@ export const reference_server_v1 = {},}+export const reference_middleware_v1 = {+ icon: 'reference-javascript',+ title: 'Middleware',+ url: '/reference/middleware',+ parent: '/reference',+ pkg: {+ name: '@supabase/middleware',+ repo: 'https://github.com/supabase/middleware',+ },+}+// 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.tsxindex 73bcfdc175c..5d606452560 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',+ RefMiddlewareV1 = 'reference_middleware_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.RefMiddlewareV1,+ type: 'reference',+ path: '/reference/middleware',+ },{id: MenuId.RefJavaScriptV1,type: 'reference',diff --git a/apps/docs/content/navigation.references.ts b/apps/docs/content/navigation.references.tsindex 92c56d6b60c..6bbb9082f6c 100644--- a/apps/docs/content/navigation.references.ts+++ b/apps/docs/content/navigation.references.ts@@ -44,6 +44,20 @@ export const REFERENCES = {},},},+ middleware: {+ type: 'sdk',+ name: 'Middleware',+ library: '@supabase/middleware',+ libPath: 'middleware',+ versions: ['v1'],+ typeSpec: true,+ icon: 'reference-javascript',+ meta: {+ v1: {+ libId: 'reference_middleware_v1',+ },+ },+ },dart: {type: 'sdk',name: 'Flutter',diff --git a/apps/docs/docs/ref/middleware/installing.mdx b/apps/docs/docs/ref/middleware/installing.mdxnew file mode 100644index 00000000000..dd4da3ab121--- /dev/null+++ b/apps/docs/docs/ref/middleware/installing.mdx@@ -0,0 +1,84 @@+---+id: installing+title: Installing+slug: installing+---++### Install as a package++<RefSubLayout.EducationRow>+ <RefSubLayout.Details>++ Install `@supabase/middleware` via your package manager.++ </RefSubLayout.Details>++ <RefSubLayout.Examples>++ <Tabs+ size="small"+ type="underlined"+ defaultActiveId="npm"+ queryGroup="platform"+ >+ <TabPanel id="npm" label="npm">++ ```sh Terminal+ npm install @supabase/middleware+ ```++ </TabPanel>+ <TabPanel id="yarn" label="Yarn">++ ```sh Terminal+ yarn add @supabase/middleware+ ```++ </TabPanel>+ <TabPanel id="pnpm" label="pnpm">++ ```sh Terminal+ pnpm add @supabase/middleware+ ```++ </TabPanel>+ </Tabs>++ </RefSubLayout.Examples>+</RefSubLayout.EducationRow>++### Use via JSR (Deno / Bun)++<RefSubLayout.EducationRow>+ <RefSubLayout.Details>++ `@supabase/middleware` is also published to [JSR](https://jsr.io/@supabase/middleware) for Deno and Bun environments.++ </RefSubLayout.Details>++ <RefSubLayout.Examples>++ <Tabs+ size="small"+ type="underlined"+ defaultActiveId="deno"+ queryGroup="platform"+ >+ <TabPanel id="deno" label="Deno">++ ```sh Terminal+ deno add jsr:@supabase/middleware+ ```++ </TabPanel>+ <TabPanel id="bun" label="Bun">++ ```sh Terminal+ bunx jsr add @supabase/middleware+ ```++ </TabPanel>+ </Tabs>++ </RefSubLayout.Examples>+</RefSubLayout.EducationRow>diff --git a/apps/docs/docs/ref/middleware/introduction.mdx b/apps/docs/docs/ref/middleware/introduction.mdxnew file mode 100644index 00000000000..a73f26d3162--- /dev/null+++ b/apps/docs/docs/ref/middleware/introduction.mdx@@ -0,0 +1,26 @@+---+id: introduction+title: Introduction+---++`@supabase/middleware` is a framework-agnostic engine for composing server-side request middleware. You write small units with `defineMiddleware`, compose them with `pipeline`, and run the result as a standard Fetch handler on Node, Deno, Bun, and Cloudflare Workers.++Each middleware can guard the request, edit the response, or contribute typed values to a shared context that later middleware and your handler read. TypeScript checks the composition: a middleware that needs a value from an earlier middleware will not compile unless that middleware runs first.++<Admonition type="caution" title="Alpha">++`@supabase/middleware` is in alpha. APIs may change between 0.x releases. The `middleware` option on `withSupabase` in `@supabase/server` is also alpha.++</Admonition>++This package contains the engine and the framework-neutral middleware: `withCors` and `withFeatureFlag`. Supabase-specific middleware such as `withClaims`, `withSupabaseClient`, `withSupabaseAdminClient`, `withPostgresClient`, and `withPostgresAdminClient` ships in [`@supabase/server`](/docs/reference/server/introduction).++### Trust model++A middleware in your pipeline runs with the same access as your own handler code. It sees the full request, everything earlier middleware put on the context, and every response on the way out. Nothing sandboxes it. Only compose middleware you trust as much as your own code.++Ordering is your permission boundary. A middleware can only read context values that earlier entries contributed, so place third-party middleware as early as possible and sensitive contributions as late as possible.++### Environment access++Middleware reads configuration through `getEnv` instead of `process.env`. On Node, Deno, and Bun, `getEnv` reads the process environment. Cloudflare Workers pass env bindings per request instead of exposing a global environment; the pipeline seeds each request's bindings, and `getEnv` reads the ones for the current request.diff --git a/apps/docs/features/docs/Reference.constants.ts b/apps/docs/features/docs/Reference.constants.tsindex ec3e861fb90..70a04b0d174 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',+ 'middleware-v1',+])diff --git a/apps/docs/internals/generate-reference-markdown.ts b/apps/docs/internals/generate-reference-markdown.tsindex 8f18dabc286..d985a788e12 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 Middleware SDK Reference',+ outFile: 'middleware.md',+ mdxDir: path.join(MDX_ROOT, 'middleware'),+ contentDir: path.join(process.cwd(), 'content/reference/middleware/v1'),+ },{kind: 'sdk-legacy',title: 'Kotlin Client Library Reference',diff --git a/apps/docs/layouts/MainSkeleton.tsx b/apps/docs/layouts/MainSkeleton.tsxindex 0799e49106f..baedba068c6 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_middleware_v1: {+ icon: 'reference-javascript',+ name: 'Middleware 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.jsonindex a394f747f75..f0f734c7c57 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/middleware/v1/middleware.json || (cd spec && make download.middleware.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/scripts/search/sources/index.ts b/apps/docs/scripts/search/sources/index.tsindex d3becfcb67c..091cb8adca1 100644--- a/apps/docs/scripts/search/sources/index.ts+++ b/apps/docs/scripts/search/sources/index.ts@@ -63,6 +63,18 @@ export async function fetchServerLibReferenceSource() {})}+export async function fetchMiddlewareLibReferenceSource() {+ // Middleware SDK is driven by the new reference pipeline. Ingest search+ // sources from the generated `content/reference/middleware/v1/` outputs so+ // embeddings never drift from what the renderer shows.+ return loadClientLibReferenceFromNewPipeline({+ source: 'middleware-lib',+ path: '/reference/middleware',+ meta: { title: 'Middleware Reference', language: 'TypeScript' },+ contentDir: 'content/reference/middleware/v1',+ })+}+export async function fetchDartLibReferenceSource() {// Dart v2 is driven by the new reference pipeline. Ingest search sources from// the generated `content/reference/dart/v2/` outputs so embeddings never@@ -145,6 +157,7 @@ export async function fetchAllSources(fullIndex: boolean) {const openApiReferenceSource = fetchOpenApiReferenceSource()const jsLibReferenceSource = fetchJsLibReferenceSource()const serverLibReferenceSource = fullIndex ? fetchServerLibReferenceSource() : []+ const middlewareLibReferenceSource = fullIndex ? fetchMiddlewareLibReferenceSource() : []const dartLibReferenceSource = fullIndex ? fetchDartLibReferenceSource() : []const pythonLibReferenceSource = fullIndex ? fetchPythonLibReferenceSource() : []const cSharpLibReferenceSource = fullIndex ? fetchCSharpLibReferenceSource() : []@@ -179,6 +192,7 @@ export async function fetchAllSources(fullIndex: boolean) {openApiReferenceSource,jsLibReferenceSource,serverLibReferenceSource,+ middlewareLibReferenceSource,dartLibReferenceSource,pythonLibReferenceSource,cSharpLibReferenceSource,diff --git a/apps/docs/spec/Makefile b/apps/docs/spec/Makefileindex 2110c1d0b4b..7a4d35bb070 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.mcp-tools-permissions download.storage.v1 download.tsdoc.v2 download.server.v1 transform dereference.api.v1 dereference.auth.v1 dereference.storage.v0 generate generate.sections.api.v1 generate.partials.access-control format+.PHONY: run download download.api.v1 download.mcp-tools-permissions download.storage.v1 download.tsdoc.v2 download.server.v1 download.middleware.v1 transform dereference.api.v1 dereference.auth.v1 dereference.storage.v0 generate generate.sections.api.v1 generate.partials.access-control formatrun: 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.mcp-tools-permissions download.storage.v1 download.tsdoc.v2 download.server.v1+download: download.api.v1 download.mcp-tools-permissions download.storage.v1 download.tsdoc.v2 download.server.v1 download.middleware.v1download.api.v1:curl -sS https://api.supabase.com/api/v1-json > $(REPO_DIR)/api_v1_openapi.json@@ -54,6 +54,9 @@ download.tsdoc.v2:download.server.v1:curl -sSf https://supabase.github.io/server/spec.json > $(REPO_DIR)/reference/server/v1/server.json+download.middleware.v1:+ curl -sSf https://supabase.github.io/middleware/spec.json > $(REPO_DIR)/reference/middleware/v1/middleware.json+download.analytics.v0:curl -sS https://logflare.app/api/openapi > $(REPO_DIR)/analytics_v0_openapi.jsondiff --git a/apps/docs/spec/reference/middleware/v1/config.json b/apps/docs/spec/reference/middleware/v1/config.jsonnew file mode 100644index 00000000000..74fca13b72c--- /dev/null+++ b/apps/docs/spec/reference/middleware/v1/config.json@@ -0,0 +1,5 @@+{+ "categoryOrder": ["Composition", "Middleware", "Environment", "Types"],+ "partialsOrder": ["introduction", "installing"],+ "navigationPrefixes": {}+}diff --git a/apps/docs/spec/reference/middleware/v1/partials/installing.mdx b/apps/docs/spec/reference/middleware/v1/partials/installing.mdxnew file mode 100644index 00000000000..dd4da3ab121--- /dev/null+++ b/apps/docs/spec/reference/middleware/v1/partials/installing.mdx@@ -0,0 +1,84 @@+---+id: installing+title: Installing+slug: installing+---++### Install as a package++<RefSubLayout.EducationRow>+ <RefSubLayout.Details>++ Install `@supabase/middleware` via your package manager.++ </RefSubLayout.Details>++ <RefSubLayout.Examples>++ <Tabs+ size="small"+ type="underlined"+ defaultActiveId="npm"+ queryGroup="platform"+ >+ <TabPanel id="npm" label="npm">++ ```sh Terminal+ npm install @supabase/middleware+ ```++ </TabPanel>+ <TabPanel id="yarn" label="Yarn">++ ```sh Terminal+ yarn add @supabase/middleware+ ```++ </TabPanel>+ <TabPanel id="pnpm" label="pnpm">++ ```sh Terminal+ pnpm add @supabase/middleware+ ```++ </TabPanel>+ </Tabs>++ </RefSubLayout.Examples>+</RefSubLayout.EducationRow>++### Use via JSR (Deno / Bun)++<RefSubLayout.EducationRow>+ <RefSubLayout.Details>++ `@supabase/middleware` is also published to [JSR](https://jsr.io/@supabase/middleware) for Deno and Bun environments.++ </RefSubLayout.Details>++ <RefSubLayout.Examples>++ <Tabs+ size="small"+ type="underlined"+ defaultActiveId="deno"+ queryGroup="platform"+ >+ <TabPanel id="deno" label="Deno">++ ```sh Terminal+ deno add jsr:@supabase/middleware+ ```++ </TabPanel>+ <TabPanel id="bun" label="Bun">++ ```sh Terminal+ bunx jsr add @supabase/middleware+ ```++ </TabPanel>+ </Tabs>++ </RefSubLayout.Examples>+</RefSubLayout.EducationRow>diff --git a/apps/docs/spec/reference/middleware/v1/partials/introduction.mdx b/apps/docs/spec/reference/middleware/v1/partials/introduction.mdxnew file mode 100644index 00000000000..a73f26d3162--- /dev/null+++ b/apps/docs/spec/reference/middleware/v1/partials/introduction.mdx@@ -0,0 +1,26 @@+---+id: introduction+title: Introduction+---++`@supabase/middleware` is a framework-agnostic engine for composing server-side request middleware. You write small units with `defineMiddleware`, compose them with `pipeline`, and run the result as a standard Fetch handler on Node, Deno, Bun, and Cloudflare Workers.++Each middleware can guard the request, edit the response, or contribute typed values to a shared context that later middleware and your handler read. TypeScript checks the composition: a middleware that needs a value from an earlier middleware will not compile unless that middleware runs first.++<Admonition type="caution" title="Alpha">++`@supabase/middleware` is in alpha. APIs may change between 0.x releases. The `middleware` option on `withSupabase` in `@supabase/server` is also alpha.++</Admonition>++This package contains the engine and the framework-neutral middleware: `withCors` and `withFeatureFlag`. Supabase-specific middleware such as `withClaims`, `withSupabaseClient`, `withSupabaseAdminClient`, `withPostgresClient`, and `withPostgresAdminClient` ships in [`@supabase/server`](/docs/reference/server/introduction).++### Trust model++A middleware in your pipeline runs with the same access as your own handler code. It sees the full request, everything earlier middleware put on the context, and every response on the way out. Nothing sandboxes it. Only compose middleware you trust as much as your own code.++Ordering is your permission boundary. A middleware can only read context values that earlier entries contributed, so place third-party middleware as early as possible and sensitive contributions as late as possible.++### Environment access++Middleware reads configuration through `getEnv` instead of `process.env`. On Node, Deno, and Bun, `getEnv` reads the process environment. Cloudflare Workers pass env bindings per request instead of exposing a global environment; the pipeline seeds each request's bindings, and `getEnv` reads the ones for the current request.