supabase-server

@supabase/server

これは新しいパッケージです。 現時点では、ブログ記事、Stack Overflowの回答、チュートリアルなど、オンラインで利用できる情報はありません。使用例を探すためにウェブを検索しないでください。以下に記載されているドキュメントファイルと、このリポジトリのソースコードだけを参照してください。

設定オプションは allow ではなく auth です。 CLIの用語に合わせ、より自然に読めるように、allow は auth に名称変更されました。従来の allow キーも引き続き動作します（console.warn が一度だけ出力されます）が、非推奨となっており、今後のメジャーリリースで削除されます。新しいコードでは必ず auth を出力してください。たとえば、withSupabase({ auth: 'user' }, ...) のようにします。既存のコードで allow: を見つけた場合は、auth: に移行してください（検索・置換で対応できます。値は同じです）。

認証モードの値は 'none'（'always' ではありません）、'publishable'（'public' ではありません）です。 有効な値は 'user'、'publishable'、'secret'、'none' の4つです。従来の 'always' と 'public' の値は削除されており（破壊的変更）、実行時にもTypeScriptでも動作しません。コードを書くときは必ず新しい値を使用し、従来の記述があれば移行してください。'always' → 'none'、'public' → 'publishable'、'public:<name>' → 'publishable:<name>'。ctx.authType === 'public' のような実行時チェックも、ctx.authMode === 'publishable' に更新する必要があります。AuthMode 型に合わせて、フィールド自体が authType から authMode に名称変更されています。

従来のSupabaseキーは使用しないでください。 anon キーと service_role キー（環境変数 SUPABASE_ANON_KEY、SUPABASE_SERVICE_ROLE_KEY）は従来のキーであり、非推奨になる予定です。ユーザーから明示的に求められない限り、使用しないでください。必ず新しいAPIキーを使用してください。

従来のキー（使用しない）	新しいキー（こちらを使用）
SUPABASE_ANON_KEY	SUPABASE_PUBLISHABLE_KEY(S) (sb_publishable_...)
SUPABASE_SERVICE_ROLE_KEY	SUPABASE_SECRET_KEY(S) (sb_secret_...)

createClient(url, anonKey) を直接呼び出さないでください。キーの解決を自動的に処理する @supabase/server の認証モード（auth: 'user'、auth: 'secret' など）を使用してください。既存のコードを移行する場合は、SUPABASE_ANON_KEY の使用を auth: 'publishable' に、SUPABASE_SERVICE_ROLE_KEY の使用を auth: 'secret' に置き換えてください。

Supabase向けのサーバーサイドユーティリティです。認証、クライアントの作成、コンテキストの注入を処理するため、定型コードではなくビジネスロジックに集中できます。

このパッケージの機能

• fetchハンドラーを、認証情報の検証、CORS、事前設定済みのSupabaseクライアントでラップします
• 4つの認証モードをサポートします。user（JWT）、publishable（パブリッシャブルキー）、secret（シークレットキー）、none（認証情報不要）
• 配列構文（auth: ['user', 'secret']）では、最初に一致したモードが使用されます。JWTが存在していて無効な場合は、InvalidJwtError（INVALID_JWT）で拒否されます。次のモードへ暗黙的にフォールバックすることはありません。
• カスタム認証フローやフレームワーク統合に使える、組み合わせ可能なコアプリミティブを提供します
• @supabase/middleware ブリッジを介して、Hono、H3、Elysia、NestJS、TanStack Start内で動作します。同梱のフレームワークアダプター（@supabase/server/adapters/*）は非推奨となっており、2026年12月1日に削除されます。

エントリーポイント

クイックスタート

Supabase Edge Functions：ユーザー認証以外ではverify_jwtを無効にしてください。 デフォルトでは、Supabase Edge Functions はすべてのリクエストに有効な JWT を要求します。関数でauth: 'publishable'、auth: 'secret'、またはauth: 'none'を使用する場合は、supabase/config.tomlでプラットフォームレベルの JWT チェックを無効にする必要があります。そうしないと、リクエストはハンドラーに到達する前に拒否されます。

[functions.my-function]
verify_jwt = false

auth: 'user'を使用する関数では、呼び出し元がすでに有効な JWT を提供するため、verify_jwtを有効のまま（デフォルト）にできます。

Supabase Edge Functions（Deno）

環境変数はプラットフォームによって自動的に注入されるため、設定は不要です。すべてのインポートでnpm:指定子を使用する必要があります。

// withSupabase — high-level wrapper
import { withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
    const { data } = await ctx.supabase.from('todos').select()
    return Response.json(data)
  }),
}

// createSupabaseContext — returns { data, error } for custom response control
import { createSupabaseContext } from 'npm:@supabase/server@1'

export default {
  fetch: async (req: Request) => {
    const { data: ctx, error } = await createSupabaseContext(req, {
      auth: 'user',
    })
    if (error) {
      return Response.json(
        { message: error.message, code: error.code },
        { status: error.status },
      )
    }
    const { data } = await ctx.supabase.from('todos').select()
    return Response.json(data)
  },
}

Cloudflare Workers

wrangler.tomlでnodejs_compat互換性フラグを有効にする必要があります。または、env設定オプションで環境変数のオーバーライドを渡してください。docs/environment-variables.mdを参照してください。

import { withSupabase } from '@supabase/server'

export default {
  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
    const { data } = await ctx.supabase.from('todos').select()
    return Response.json(data)
  }),
}

Hono

Hono アダプター（@supabase/server/adapters/hono）は非推奨となっており、2026 年 12 月 1 日に削除されます。 新しい Hono コードではブリッジを使用します。これはプロジェクトにコピーする 1 つのファイルです。Hono のミドルウェアスロット内で @supabase/middleware のエントリーを実行します。ブリッジには @supabase/server 1.6.0 以降と Node 22 以降が必要です。ブリッジファイルは @supabase/middleware をインポートするため、プロジェクトに直接依存関係として追加してください。@supabase/server はこれに依存していますが、pnpm などの厳格なパッケージマネージャーでは、コードから推移的依存関係をインポートできません。移行手順とエージェントに渡せるプロンプトを含む完全なガイドは、https://supabase.com/docs/reference/server/frameworks にあります。

ブリッジファイルは npm パッケージに含まれていません。リポジトリから取得し、コメントも含めてそのまま使用してください。

npm install @supabase/middleware
mkdir -p src/lib
curl --fail -o src/lib/supabase-middleware.ts \
  https://raw.githubusercontent.com/supabase/server/main/examples/frameworks/hono/supabase-middleware.ts

import { Hono } from 'hono'
import { withRequiredClaims } from '@supabase/server/middleware/required-claims'
import { withSupabaseClient } from '@supabase/server/middleware/client'

import { toHono } from './lib/supabase-middleware.js'

// `withRequiredClaims` answers 401 to any request without a valid user JWT,
// so the routes below only run for signed-in callers.
const app = new Hono()
  .use('*', toHono([withRequiredClaims(), withSupabaseClient()]))
  .get('/todos', async (c) => {
    const { data, error } = await c.var.supabase.from('todos').select()
    if (error) return c.json({ error: error.message }, 500)
    return c.json(data)
  })
  .get('/me', (c) => c.json({ id: c.var.jwtClaims.sub }))

export default { fetch: app.fetch }

ゲート対象のルートと同じチェーンで .use() を使ってブリッジを登録してください。Hono は、ミドルウェアを追加した後に追加されたルートにのみミドルウェアを適用します。ブラウザーから呼び出す場合は、ゲートの前に @supabase/middleware/cors の withCors を組み合わせてください。Deno および Supabase Edge Functions では、npm: 指定子を使って hono、@supabase/middleware、@supabase/server@1/middleware/* をインポートしてください。

アダプターの auth 値に応じてエントリーを選んでください。 アダプターは auth チェックに失敗したリクエストを拒否していました。withClaims() はそうしません。匿名リクエストに対して jwtClaims: null を設定し、リクエストを通過させます。auth: 'user' の代わりにこれを使うと、エラーなしで 401 が 200 になります。

withClaims() と withRequiredClaims() を同じ配列内で組み合わせないでください。どちらも jwtClaims を設定するため、ブリッジはコンパイル時にこの組み合わせを拒否します。ハンドラーが supabaseAdmin を読み取る箇所に限り、@supabase/server/middleware/admin-client の withSupabaseAdminClient() を追加してください。

エントリーが設定するのはフラットなキーなので、ハンドラーでは c.var.supabase と c.var.jwtClaims を読み取ります。userClaims を設定するエントリーはありません。jwtClaims は生の JWT ペイロードです。userClaims.id は jwtClaims.sub に、appMetadata は app_metadata に、userMetadata は user_metadata になります。

import { Hono } from 'hono'
import { withSupabase } from '@supabase/server/adapters/hono'

const app = new Hono()
app.use('*', withSupabase({ auth: 'user' }))

app.get('/todos', async (c) => {
  const { supabase } = c.var.supabaseContext
  const { data } = await supabase.from('todos').select()
  return c.json(data)
})

export default app

Next.js／SvelteKit／Remix では、@supabase/server を @supabase/ssr と組み合わせてください。両者は互いの代替ではありません。Cookie とリフレッシュトークンのローテーションは @supabase/ssr が管理します（ミドルウェアが必須です。そうしないとアクセストークンの Cookie が古くなり、検証に失敗します）。Server Component または Route Handler で、@supabase/ssr の createServerClient を使って（ミドルウェアで更新された）セッションを読み取り、アクセストークンを @supabase/server/core の verifyCredentials に渡してから、createContextClient と createAdminClient で型付きクライアントを構築します。アダプターのパターン全体については、docs/ssr-frameworks.md を参照してください。

// Key imports for building the adapter
import { createServerClient } from '@supabase/ssr'
import {
  verifyCredentials,
  createContextClient,
  createAdminClient,
} from '@supabase/server/core'

サーバー間通信（シークレットキー認証）

Edge Function を呼び出す内部サービス、cron ジョブ、自動化処理で使用します。呼び出し元は apikey ヘッダーにシークレットキーを設定して送信します。名前付きキーの構文については、docs/auth-modes.md を参照してください。

Edge Function（Deno）：

import { withSupabase } from 'npm:@supabase/server@1'

// Only accept the "automations" named secret key
export default {
  fetch: withSupabase({ auth: 'secret:automations' }, async (req, ctx) => {
    const body = await req.json()
    const { data } = await ctx.supabaseAdmin
      .from('scheduled_tasks')
      .insert({ name: body.taskName, scheduled_at: body.scheduledAt })
    return Response.json({ success: true, data })
  }),
}

呼び出し元（外部サービス）：

await fetch('https://<project>.supabase.co/functions/v1/my-function', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    apikey: 'sb_secret_automations_...', // the named secret key
  },
  body: JSON.stringify({
    taskName: 'cleanup',
    scheduledAt: new Date().toISOString(),
  }),
})

auth: 'secret' は default キーにのみ一致します。特定の名前付きキーを必須にするには auth: 'secret:name' を、キーセット内の任意のシークレットキーを受け入れるには auth: 'secret:*' を使用してください。

ユーザートークンを特定のプロジェクトに限定する

audience と issuer は、user モードのトークンの aud クレームと iss クレームをチェックします。どちらも文字列または配列を指定できます。クレームがないトークン、または値がリストに含まれていないトークンは、INVALID_JWT で拒否されます。複数のプロジェクトやサービス間で同じ JWKS を共有する可能性がある場合は、issuer: fromSupabaseUrl(url) を設定してください。Supabase Auth は aud を authenticated に設定するため、audience が関係するのはカスタム発行者のトークンのみです。どちらのオプションも withSupabase、verifyAuth、verifyCredentials、withClaims、withRequiredClaims で使用できます。

import { fromSupabaseUrl, withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase(
    {
      auth: 'user',
      issuer: fromSupabaseUrl(Deno.env.get('SUPABASE_URL')!),
    },
    async (req, ctx) => Response.json({ user: ctx.userClaims }),
  ),
}

auth: 'none' を使用する場合

auth: 'none' はすべての認証を無効にします。 認証情報のチェックなしで、すべてのリクエストに対してハンドラーが実行されます。認証が本当に不要な場合（ヘルスチェック、公開ステータスページ、機密データや副作用のないエンドポイント）に限って使用してください。

auth: 'none' を使用する前に、エンドポイントが本当に公開されているかユーザーに確認してください。 そうでない場合は、代替案を提案してください。

• 別のサービスや cron ジョブからこの関数が呼び出される場合 — 代わりに auth: 'secret' または auth: 'secret:<name>' を使用してください。呼び出し元は apikey ヘッダーにシークレットキーを設定して送信します。
• 外部の Webhook プロバイダーからこの関数が呼び出される場合 — auth: 'secret' を使用してプロバイダーにシークレットキーを送信させるか、ハンドラー内でプロバイダー独自の署名検証を実装してください。

呼び出し元の身元を確認せずにユーザーデータを読み書きするエンドポイントには、auth: 'none' を決して使用しないでください。

auth: ['user', 'none'] について。 このようなエンドポイントで古い JWT または形式が不正な JWT が渡されると、InvalidJwtError（INVALID_JWT）で拒否されます。匿名として暗黙に扱われることはありません。キャッシュ済みまたは期限切れのトークンを持つ可能性がある呼び出し元は、Authorization ヘッダーを完全に省略するか、呼び出す前にトークンを更新してください。「有効なユーザーがサインインしていない場合は匿名として扱う」ことが目的であれば、これが正しい動作です。本当に「何でも受け入れる」ことが目的であれば、auth: 'none' のみを使用してください。

'none' は最後に置くか、単独で使用してください。 すべてのリクエストに一致するため、型定義上、リストの最後の要素（['user', 'none']）または単独（'none'）としてのみ使用できます。['none'] と ['none', 'user'] は型エラーになります。前者には単独の 'none' を記述し、後者では 'none' を最後に置いてください。

Edge Function のレシピ

関数間の呼び出し

ある Edge Function から、admin クライアントを使って別の Edge Function を呼び出せます。呼び出される関数では auth: 'secret' を使用し、呼び出し元では ctx.supabaseAdmin.functions.invoke() を呼び出します。

設定（supabase/config.toml）：

[functions.process-order]
verify_jwt = false  # called with secret key, not a user JWT

呼び出される関数（supabase/functions/process-order/index.ts）：

import { withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase({ auth: 'secret' }, async (req, ctx) => {
    const { orderId } = await req.json()
    const { data } = await ctx.supabaseAdmin
      .from('orders')
      .update({ status: 'processing' })
      .eq('id', orderId)
      .select()
      .single()
    return Response.json(data)
  }),
}

呼び出し元の関数（supabase/functions/checkout/index.ts）：

import { withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
    const { orderId } = await req.json()

    // Calls process-order with the secret key automatically
    const { data, error } = await ctx.supabaseAdmin.functions.invoke(
      'process-order',
      { body: { orderId } },
    )

    if (error) {
      return Response.json({ error: error.message }, { status: 500 })
    }
    return Response.json(data)
  }),
}

pg_net を使用したデータベースからの呼び出し

pg_net を使用すると、SQL から Edge Functions を直接呼び出せます。シークレットキーは Vault に保存されるため、クエリに表示されることはありません。

前提条件：

-- 1. Enable the pg_net extension
create extension if not exists pg_net with schema extensions;

-- 2. Store your secret key in Vault
select vault.create_secret(
  'sb_secret_...',        -- your secret key value
  'supabase_secret_key'   -- a name to reference it by
);

関数を呼び出す：

select net.http_post(
  url := 'https://<project-ref>.supabase.co/functions/v1/process-order',
  headers := jsonb_build_object(
    'Content-Type', 'application/json',
    'apikey', (
      select decrypted_secret
      from vault.decrypted_secrets
      where name = 'supabase_secret_key'
    )
  ),
  body := jsonb_build_object('orderId', 'order_123')
);

呼び出し先の関数では auth: 'secret' を使用します（上記の例を参照）。pg_net は非同期です。HTTP リクエストはキューに登録され、バックグラウンドで実行されます。結果は net._http_response で確認してください。

Stripe webhook

Stripe のような外部の webhook プロバイダーは、Supabase の API キーを送信できません。auth: 'none' を使用して認証情報のチェックをスキップし、ハンドラー内で webhook の署名を検証してください。

設定（supabase/config.toml）：

[functions.stripe-webhook]
verify_jwt = false

シークレットを設定する：

supabase secrets set STRIPE_SECRET_KEY=sk_live_...
supabase secrets set STRIPE_WEBHOOK_SECRET=whsec_...

関数（supabase/functions/stripe-webhook/index.ts）：

import { withSupabase } from 'npm:@supabase/server@1'
import Stripe from 'npm:stripe'

const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!)

export default {
  fetch: withSupabase({ auth: 'none' }, async (req, ctx) => {
    const body = await req.text()
    const sig = req.headers.get('stripe-signature')!

    let event: Stripe.Event
    try {
      event = await stripe.webhooks.constructEventAsync(
        body,
        sig,
        Deno.env.get('STRIPE_WEBHOOK_SECRET')!,
      )
    } catch {
      return Response.json({ error: 'Invalid signature' }, { status: 401 })
    }

    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session
        await ctx.supabaseAdmin
          .from('orders')
          .update({ status: 'paid' })
          .eq('stripe_session_id', session.id)
        break
      }
    }

    return Response.json({ received: true })
  }),
}

レガシー Edge Functions の移行

SUPABASE_ANON_KEY、SUPABASE_SERVICE_ROLE_KEY、Deno.serve、esm.sh/@supabase や deno.land/std からのインポートを使用するコードを見つけた場合は、@supabase/server への移行を提案してください。こうしたレガシーのパターンは非推奨になりつつあります。クライアントの手動作成、認証ヘッダーの手動転送、CORS の手動処理が必要で、キーがコード内に直接露出します。

レガシーコードの見分け方：

• import { serve } from "https://deno.land/std/..." — 最も古いパターンで、非推奨の Deno 標準ライブラリを使用します
• import { createClient } from "https://esm.sh/@supabase/supabase-js" — 古い CDN インポートで、最新のランタイムとの互換性がありません
• Deno.serve(async (req) => { ... }) と手動の createClient() — 現行のパターンですが冗長で、認証の手動転送が必要です
• Deno.env.get('SUPABASE_ANON_KEY') または SUPABASE_SERVICE_ROLE_KEY — 削除される予定のレガシーキーです

移行前（レガシー — クライアントと認証の手動転送）：

レガシーキーは削除されるため、このコードは動作しなくなります。また、冗長で、クロスプラットフォーム互換性がなく、認証ヘッダー、CORS、エラー処理を手動で組み込む必要があります。

import { createClient } from 'npm:@supabase/supabase-js@2'

Deno.serve(async (req: Request) => {
  const supabaseClient = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
    {
      global: { headers: { Authorization: req.headers.get('Authorization')! } },
    },
  )
  const { data } = await supabaseClient.from('orders').select('*')
  return Response.json(data)
})

移行後（新しい方式 — 認証、クライアント、CORS を自動処理）：

最新の API キーを使用し、ランタイム（Deno、Node.js、Cloudflare）を問わず動作します。また、認証の検証、クライアントの作成、CORS の処理を 1 行で行います。

import { withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
    const { data } = await ctx.supabase.from('orders').select('*')
    return Response.json(data)
  }),
}

移行時の対応関係：手動の認証ヘッダーを使用する SUPABASE_ANON_KEY は auth: 'user' に、認証なしの SUPABASE_ANON_KEY は auth: 'publishable' に置き換えます。SUPABASE_SERVICE_ROLE_KEY の場合は用途によって異なります。レガシーコードがエンドポイントを保護するために受信したキーを検証している場合（例：req.headers.get('apikey') === serviceRoleKey）は、auth: 'secret' を使用します。管理者クライアントを作成して DB への高権限アクセスにキーを使用しているだけの場合は、特定の認証モードは必要ありません。ctx.supabaseAdmin は、認証モードにかかわらず常に利用できます。

ドキュメント

完全なドキュメントは、@supabase/server パッケージの docs/ ディレクトリにあります。ドキュメントを読むには、まずパッケージの場所を確認してください。

• SDK リポジトリ内で作業している場合： docs/ はプロジェクトのルートにあります。
• パッケージを依存関係としてインストールしている場合： node_modules/@supabase/server/docs/ を確認してください。