feat(core): expose defineAdapter via @supabase/server/core/adapters subpath

Author: johnstonmatt

jsr.json

@@ -5,6 +5,7 @@
     ".": "./src/index.ts",
     "./core": "./src/core/index.ts",
     "./core/gates": "./src/core/gates/index.ts",
+    "./core/adapters": "./src/core/adapters/index.ts",
     "./adapters/hono": "./src/adapters/hono/index.ts",
     "./adapters/h3": "./src/adapters/h3/index.ts",
     "./adapters/elysia": "./src/adapters/elysia/index.ts",

package.json

@@ -34,6 +34,11 @@
       "import": "./dist/core/gates/index.mjs",
       "require": "./dist/core/gates/index.cjs"
     },
+    "./core/adapters": {
+      "types": "./dist/core/adapters/index.d.mts",
+      "import": "./dist/core/adapters/index.mjs",
+      "require": "./dist/core/adapters/index.cjs"
+    },
     "./adapters/hono": {
       "types": "./dist/adapters/hono/index.d.mts",
       "import": "./dist/adapters/hono/index.mjs",

src/adapters/README.md

@@ -27,7 +27,7 @@ Before you start, **read [`CONTRIBUTING.md`](../../CONTRIBUTING.md) and agree wi
 - **Tests for every auth mode.** Cover `'user'`, `'publishable'`, `'secret'`, `'none'`, the array form, and the failure paths (missing token, invalid JWT, missing apikey). The Hono adapter's [`hono/middleware.test.ts`](hono/middleware.test.ts) is the canonical reference — your test file should look structurally similar.
 - **Strict TypeScript.** No `any`, no `// @ts-ignore`. Public types must be exported from the adapter's `index.ts` so consumers can extend them.
 - **No new runtime dependencies** beyond the framework you're adapting. The framework itself goes in `peerDependencies` (and `peerDependenciesMeta` if optional). Don't pull in a wrapper, polyfill, or utility lib just to make the adapter shorter.
-- **Match the existing adapter shape.** Export `withSupabase` with two call forms — `withSupabase(config)` returning the framework's native middleware/plugin, and `withSupabase(config, handler)` returning a dual-mode route handler built via [`defineAdapter`](../core/define-adapter.ts) (see [Designing an adapter](#designing-an-adapter) below). Use `verifyAuth`, `createContextClient`, and `createAdminClient` from `@supabase/server/core` — never re-implement auth or env handling inside an adapter.
+- **Match the existing adapter shape.** Export `withSupabase` with two call forms — `withSupabase(config)` returning the framework's native middleware/plugin, and `withSupabase(config, handler)` returning a dual-mode route handler built via [`defineAdapter`](../core/adapters/define-adapter.ts) (see [Designing an adapter](#designing-an-adapter) below). Use `verifyAuth`, `createContextClient`, and `createAdminClient` from `@supabase/server/core` — never re-implement auth or env handling inside an adapter.
 - **Wire up the build outputs.** Add the adapter entry to `package.json#exports`, `jsr.json` (if applicable), and `tsdown.config.ts#entry` so it ships in the published artifact.
 - **Docs are required.** Add `docs/adapters/<name>.md` mirroring the structure of [`docs/adapters/hono.md`](../../docs/adapters/hono.md) — at minimum: setup, basic example, per-route auth, CORS note.
 - **Update both adapter tables.** Add a row to the table in this `src/adapters/README.md` _and_ the mirror table in the top-level [`README.md`](../../README.md). Keep the framework-version column accurate against `package.json#peerDependencies`. PRs that touch an existing adapter must update the version column if the peer-dep range changed.
@@ -58,7 +58,7 @@ Common contract every one-arg implementation must uphold:
 
 `withSupabase(config, handler)` returns a dual-mode route handler that accepts either a `Request` (Web Fetch use) or the framework's native route input (`Context`, `H3Event`, Elysia args), extracts the underlying Request, and runs base `withSupabase` against it. Mountable directly via `app.all(path, withSupabase(config, handler))`.
 
-Don't hand-roll this — [`defineAdapter`](../core/define-adapter.ts) encapsulates the entire dual-mode contract, including:
+Don't hand-roll this — [`defineAdapter`](../core/adapters/define-adapter.ts) (exported publicly as `@supabase/server/core/adapters`) encapsulates the entire dual-mode contract, including:
 
 - Request extraction from the framework's native input.
 - `cors: false` forced on the base call (the framework owns CORS).
@@ -68,7 +68,11 @@ Don't hand-roll this — [`defineAdapter`](../core/define-adapter.ts) encapsulat
 Wire it up at the top of your adapter file:
 
 ```ts
-import { defineAdapter } from '../../core/define-adapter.js'
+// In-tree (bundled adapters in this repo):
+import { defineAdapter } from '../../core/adapters/index.js'
+
+// Third-party adapter published as its own npm package:
+// import { defineAdapter } from '@supabase/server/core/adapters'
 
 const adapterWithSupabase = defineAdapter<MyFrameworkContext>({
   name: 'my-framework',

src/adapters/elysia/plugin.ts

@@ -1,7 +1,7 @@
 import { Elysia, type ExtractErrorFromHandle } from 'elysia'
 
 import { createSupabaseContext } from '../../create-supabase-context.js'
-import { defineAdapter } from '../../core/define-adapter.js'
+import { defineAdapter } from '../../core/adapters/index.js'
 import type { AuthError } from '../../errors.js'
 import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
 

src/adapters/h3/middleware.ts

@@ -2,7 +2,7 @@ import { defineMiddleware, HTTPError } from 'h3'
 import type { H3Event, Middleware } from 'h3'
 
 import { createSupabaseContext } from '../../create-supabase-context.js'
-import { defineAdapter } from '../../core/define-adapter.js'
+import { defineAdapter } from '../../core/adapters/index.js'
 import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
 
 const adapterWithSupabase = defineAdapter<H3Event>({

src/adapters/hono/middleware.ts

@@ -3,7 +3,7 @@ import { HTTPException } from 'hono/http-exception'
 import { createMiddleware } from 'hono/factory'
 
 import { createSupabaseContext } from '../../create-supabase-context.js'
-import { defineAdapter } from '../../core/define-adapter.js'
+import { defineAdapter } from '../../core/adapters/index.js'
 import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
 
 const adapterWithSupabase = defineAdapter<Context>({

src/core/define-adapter.test.ts src/core/adapters/define-adapter.test.tssrc/core/define-adapter.test.ts renamed to src/core/adapters/define-adapter.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { AuthError } from '../errors.js'
-import type { SupabaseContext, WithSupabaseConfig } from '../types.js'
+import { AuthError } from '../../errors.js'
+import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
 
 import { defineAdapter } from './define-adapter.js'
 
 const baseMock = vi.hoisted(() => ({ withSupabase: vi.fn() }))
-vi.mock('../with-supabase.js', () => baseMock)
+vi.mock('../../with-supabase.js', () => baseMock)
 
 interface FakeContext {
   request: Request

src/core/define-adapter.ts src/core/adapters/define-adapter.tssrc/core/define-adapter.ts renamed to src/core/adapters/define-adapter.ts

@@ -1,6 +1,6 @@
-import type { AuthError } from '../errors.js'
-import type { SupabaseContext, WithSupabaseConfig } from '../types.js'
-import { withSupabase as baseWithSupabase } from '../with-supabase.js'
+import type { AuthError } from '../../errors.js'
+import type { SupabaseContext, WithSupabaseConfig } from '../../types.js'
+import { withSupabase as baseWithSupabase } from '../../with-supabase.js'
 
 /**
  * Spec for {@link defineAdapter}.
@@ -77,12 +77,11 @@ export interface AdapterSpec<NativeContext> {
  * adapter's responsibility; `defineAdapter` only covers the two-arg
  * form.
  *
- * @example
+ * @example Third-party adapter package
  * ```ts
- * // adapters/hono/middleware.ts
  * import type { Context } from 'hono'
  * import { HTTPException } from 'hono/http-exception'
- * import { defineAdapter } from '../../core/define-adapter.js'
+ * import { defineAdapter } from '@supabase/server/core/adapters'
  *
  * const adapterWithSupabase = defineAdapter<Context>({
  *   name: 'hono',

src/core/adapters/index.ts

@@ -0,0 +1 @@
+export { defineAdapter, type AdapterSpec } from './define-adapter.js'

tsdown.config.ts

@@ -5,6 +5,7 @@ export default defineConfig({
     'src/index.ts',
     'src/core/index.ts',
     'src/core/gates/index.ts',
+    'src/core/adapters/index.ts',
     'src/adapters/hono/index.ts',
     'src/adapters/h3/index.ts',
     'src/gates/feature-flag/index.ts',