code · pull · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026
diff --git 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.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.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.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.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.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/features/docs/Reference.ui.tsx b/apps/docs/features/docs/Reference.ui.tsx
@@ -474,7 +474,9 @@ export function ApiSchemaParamSubdetails({
   if (
     !('enum' in schema) &&
     'type' in schema &&
-    (['boolean', 'number', 'integer'].includes(schema.type) ||
+    (schema.type === 'boolean' ||
+      ((schema.type === 'number' || schema.type === 'integer') &&
+        !('minimum' in schema || 'maximum' in schema)) ||
       (schema.type === 'string' &&
         !('minLength' in schema || 'maxLength' in schema || 'pattern' in schema)) ||
       (schema.type === 'array' &&
@@ -501,7 +503,15 @@ export function ApiSchemaParamSubdetails({
                     constraint: key,
                     value: schema[key],
                   }))
-              : []
+              : 'type' in schema && (schema.type === 'number' || schema.type === 'integer')
+                ? ['minimum', 'maximum']
+                    .filter((key) => key in schema)
+                    .map((key) => ({
+                      constraint: key,
+                      value: schema[key],
+                    }))
+                : []
+
   const subContent = asSchemaArray(rawSubContent)
 
   return (
@@ -575,7 +585,10 @@ export function ApiSchemaParamSubdetails({
                   <span className="font-mono text-sm font-medium text-foreground">
                     {String(detail)}
                   </span>
-                ) : 'type' in schema && schema.type === 'string' ? (
+                ) : 'type' in schema &&
+                  (schema.type === 'string' ||
+                    schema.type === 'number' ||
+                    schema.type === 'integer') ? (
                   <span className="text-sm text-foreground flex items-baseline gap-2">
                     <span className="font-mono text-sm font-medium text-foreground">
                       {detail.constraint}

diff --git 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.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.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/public/humans.txt b/apps/docs/public/humans.txt
@@ -265,6 +265,7 @@ Ryan Goulet
 Ryan Senior
 Ruan Maia
 Saba Pochkhua
+Safa Orhan
 Sagar Shedge
 Sam Meech-Ward
 Sam Rome
@@ -313,6 +314,7 @@ Tom Ashley
 Tom G
 Tomás Pozo
 Tomás Torgal
+Tomohiro Mitani
 Tyler Hillery
 Tyler Fontaine
 Tyler Shukert

diff --git 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/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 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.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.v1
 
 download.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.json
 

diff --git a/apps/docs/spec/reference/middleware/v1/config.json b/apps/docs/spec/reference/middleware/v1/config.json
@@ -0,0 +1,5 @@
+{
+  "categoryOrder": ["Composition", "Middleware", "Environment", "Types"],
+  "partialsOrder": ["introduction", "installing"],
+  "navigationPrefixes": {}
+}