TL;DR

Supabase vừa publish @supabase/server lên npm — một lớp tiện ích server-side bọc quanh @supabase/supabase-js. Một hàm duy nhất, withSupabase(config, handler), lo: validate JWT/API key, tạo client đúng scope (RLS hoặc admin), xử lý CORS. Handler của bạn chỉ còn business logic. Hiện beta v0.1.4 (publish 2026-04-01), MIT, peer với supabase-js ^2.0.0. Được announce bởi CEO Paul Copplestone.

What's new

Trước đây viết một Edge Function "đơn giản" thường kéo theo boilerplate lặp lại: tạo hai client (anon + service_role), tự parse Authorization header, gọi auth.getUser(), copy-paste khối CORS headers, rồi mới đến logic thật. @supabase/server gom toàn bộ phần đó vào một wrapper:

import { withSupabase } from '@supabase/server'

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

Một import, một config, auth được validate, client được scope đúng, CORS tự bật. Handler chỉ chạy khi auth đã pass.

Technical facts

  • Tên package: @supabase/server — publish lần đầu 2026-03-24, latest 0.1.4 (2026-04-01)
  • Peer deps: @supabase/supabase-js ^2.0.0, hono ^4.0.0
  • Runtime dep duy nhất: jose ^6.2.0 (JWT verify)
  • Exports: ., ./core (primitives), ./adapters/hono
  • Runtime-agnostic: Deno, Bun, Node, Cloudflare Workers — bất kỳ runtime hỗ trợ pattern { fetch }
  • License MIT, repo github.com/supabase/server

Context object inject vào handler:

interface SupabaseContext {
  supabase: SupabaseClient       // RLS-scoped (user or anon)
  supabaseAdmin: SupabaseClient  // bypasses RLS
  userClaims: UserClaims | null  // id, email, role from JWT
  claims: JWTClaims | null
  authType: Allow                // which mode matched
}

Auth modes

ModeCredentialUse case
user (default)Valid JWTAuthenticated user endpoints
publicPublishable keyClient-facing endpoints validate key
secretSecret keyServer-to-server, internal calls
alwaysNoneOpen endpoints, DIY auth

Hỗ trợ cú pháp mảng (allow: ['user','secret'] — first match wins) và named key (allow: 'secret:automations' để match đúng key tên "automations").

Comparison

Đừng nhầm với @supabase/ssr (latest 0.10.2) — hai package giải hai bài khác nhau:

PackageGiải bài toánCredential chínhTarget
@supabase/ssrHydrate session từ cookie khi SSR trangCookiesNext.js / Nuxt / SvelteKit pages
@supabase/serverBọc handler API / Edge FunctionJWT hoặc API keyEdge Functions, REST endpoints, Hono apps

So với tự viết: createClient hai lần, verify header, CORS copy-paste — withSupabase collapse tất cả về một config object. So với Supabase Auth Helpers (đã deprecated), đây là bước kế tiếp cho phía server endpoint.

Use cases

  • Edge Functions: export { fetch: withSupabase(...) }. Nếu dùng mode public/secret/always, tắt platform JWT check trong supabase/config.toml bằng verify_jwt = false theo từng function.
  • REST endpoints có RLS: handler dùng ctx.supabase, RLS tự lo authz — không cần code phân quyền trong app.
  • Server-to-server: allow: 'secret:cron' chỉ chấp nhận key tên "cron". Caller gửi key qua header apikey.
  • Dual auth: allow: ['user','secret'] cho endpoint vừa user gọi vừa service gọi được; ctx.userClaims?.id ?? body.user_id.
  • Hono apps: import từ @supabase/server/adapters/hono, áp theo từng route; CORS để hono/cors lo.
  • Custom routers: dùng primitives verifyAuth + createContextClient từ @supabase/server/core khi withSupabase quá opinionated.

Limitations & pricing

  • Beta. README ghi rõ "APIs and documentation may change." Chưa nên pin vào production mà không test kỹ.
  • Mới có một framework adapter (Hono). Next/Nuxt/SvelteKit/Remix tạm dùng withSupabase base hoặc ./core.
  • Không bundle rate limiting, logging, tracing — tự mang middleware.
  • Chưa có benchmark chính thức.
  • Free, MIT. Không phát sinh chi phí Supabase — chỉ là wrapper SDK.

What's next

Hướng phát triển có thể dự đoán từ state repo: thêm adapter cho Next.js / Nuxt / SvelteKit / Remix, ổn định API hướng 1.0, và tích hợp chặt hơn với template CLI của Supabase Edge Functions. Tốc độ release cho thấy nhóm đang chạy nhanh — từ alpha đầu tiên (2026-03-24) đến 0.1.4 chỉ mất đúng một tuần, với hơn 37 release candidate trước đó. Nếu bạn đang viết Edge Function hoặc API route có dính auth Supabase, đây là lúc thử bản beta để góp feedback trước khi API đông cứng. Một điểm đáng để ý: README nhắc tới lệnh npx skills add supabase/server để cài skill cho AI coding agent (Claude Code, Cursor) — tín hiệu rõ là Supabase đang coi AI-assisted DX như một first-class distribution channel, không chỉ tài liệu tĩnh.

Cài thử:

npm install @supabase/server

Nguồn: npm @supabase/server, GitHub repo, Supabase server-side auth docs.