Skip to content

MIGRATION.md

Latest commit

 

History

History
79 lines (48 loc) · 3.23 KB

MIGRATION.md

File metadata and controls

79 lines (48 loc) · 3.23 KB
Raw

Migration Guide

Cross-cutting migration notes for the Supabase JavaScript SDK. One H2 section per migration theme.

Per-package migrations (changes scoped to a single SDK like @supabase/auth-js) live alongside the package they affect, under packages/core/<package>/migrations/. The notes in this file cover changes that span multiple packages or the workspace as a whole.

Edge Functions auth headers

Edge Function calls (supabase.functions.invoke()) now keep the apikey and Authorization headers distinct, matching the Server SDK pattern:

  • The API key is always sent in the apikey header.
  • Authorization carries the signed-in user's JWT (or a custom auth token). When there is no user session, a new-format API key (sb_publishable_… / sb_secret_…) is no longer sent as Authorization: Bearer <key> — new-format keys are not JWTs, and the gateway now accepts apikey-only requests (including for verify_jwt=true functions).

This does not affect other services (Database/PostgREST, Storage, Realtime), and legacy JWT keys are unchanged (they are still sent in Authorization for backward compatibility).

What to do

Nothing for the vast majority of users — authenticated calls still send the user's JWT, and unauthenticated calls continue to work via the apikey header.

The only impacted case is code that reads the API key out of the Authorization header inside an Edge Function (e.g. a server-side check on Bearer sb_...). Those cases should read the apikey header instead, or migrate to @supabase/server for edge functions.

Node.js 18 support dropped (v2.79.0, 2025-10-31)

Starting with version 2.79.0, all Supabase JavaScript libraries require Node.js 20 or later. The @supabase/node-fetch polyfill has been removed and native fetch is now required.

Affected packages

@supabase/supabase-js, @supabase/auth-js, @supabase/postgrest-js, @supabase/realtime-js, @supabase/storage-js, @supabase/functions-js.

Why

Node.js 18 reached end-of-life on April 30, 2025 and no longer receives security updates. Node.js 20+ ships with native fetch, eliminating the need for the polyfill and reducing bundle size.

What to do

  1. Upgrade Node.js to version 20 or later:

    # Check current version
node --version

# Via nvm
nvm install 20
nvm use 20

# Or download from https://nodejs.org/

  2. Update your dependencies:

    npm install @supabase/supabase-js@latest
# or, per-package:
npm install @supabase/auth-js@latest

  3. No code changes required — APIs are unchanged.

Supported runtimes

  • Node.js 20+ (native fetch)
  • Modern browsers
  • Deno 2.x
  • Bun 0.1+
  • React Native and Expo (with the framework's bundled fetch polyfill)

Troubleshooting

fetch is not defined — you're on Node.js < 20. Upgrade Node.js. If you absolutely cannot upgrade, pin to the last version that supported Node.js 18:

npm install @supabase/supabase-js@2.78.0

⚠️ Using Node.js 18 is not recommended — it no longer receives security updates.

Reference

Deprecation announcement.