npm / @supabase/supabase-js
@supabase/supabase-js
What changed in @supabase/supabase-js 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
12 breaking1 security1 deprecations52 new APIs and options5 behavior and defaults1 tooling168 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@supabase/supabase-js 2240 changes
Breaking changes 12
Computed fields are left out of select('*'), changing which fields are included when selecting all.
Enables the passkey API by default.
Node.js 20 is no longer supported.
auth.resend() now uses a consistent confirmation flow.
The fix that encoded the client ID in OAuth requests was reverted.
The client info header now uses a structured metadata format.
Blocks setting a postgres_changes event listener after joining.
The default lockAcquireTimeout is lowered to 5 seconds.
The default realtime serializer is now 2.0.0.
The storage analytics from method now follows the { data, error } return pattern.
Renames StorageAnalyticsApi to StorageAnalyticsClient, changing the name developers use for the Storage Analytics API.
Node.js 20+ is required; node-fetch was removed.
Security 1
PostgREST adds URL length validation, affecting requests with long URLs.
Deprecations 1
Deprecates the experimental passkey opt-in.
New APIs and options 52
Uploads support content-encoding.
Adds support for bucket lifecycle configuration.
Adds an API for MFA recovery codes.
Adds support for topk values up to 10k.
Create URL methods now support versionId.
Adds getOpenApiSpec() to postgrest for retrieving the OpenAPI specification.
Realtime now allows waiting for Postgres changes.
OpenTelemetry tracing is available through an opt-in /tracing subpath.
Adds custom_claims_allowlist to the custom providers admin API.
Adds a postgres_changes filter builder, new operators, and select.
Exposes purgeCache for buckets and individual objects.
Adds an option for the replication connection system message.
Auth removes the navigator.locks-based mutex and introduces a commit guard and dispose() for cleanup.
Adds W3C/OpenTelemetry trace context propagation.
Adds WebAuthn registration, authentication, and management support for passkeys.
Adds deferred disconnect support in Realtime.
Adds the cacheNonce parameter to downloads.
Adds a PostgREST method for stripping null values.
PostgrestFilterBuilder is now exported from supabase-js for direct use.
StorageApiError is now exported from supabase-js for direct use.
PostgREST response types now include a success discriminator field.
Adds copyBindings functionality to realtime.
Adds RateLimitError to the Deno.errors namespace.
Adds admin CRUD methods for custom OIDC/OAuth providers.
The Provider type supports custom providers using the custom: prefix.
OAuth client create and update operations accept token_endpoint_auth_method.
The UserAttributes type adds currentPassword.
Adds an auth option to prevent automatic initialization in the constructor.
Adds the setHeader method to BaseApiClient.
Adds a canonical CORS headers export for edge functions.
Exposes fetch parameters in the download method.
Adds missing HTTP headers used for client platform and runtime detection.
Adds an optional jwt parameter to getAuthenticatorAssuranceLevel.
Heartbeat callbacks now expose heartbeat latency.
A configurable lock acquisition timeout is available to prevent deadlocks.
AMR claims now support string arrays.
Exports the DatabaseWithoutInternals utility type.
Adds the X (OAuth 2.0) provider for authentication.
The option now accepts a custom predicate for detecting a session in the URL.
A notin filter is now available in PostgREST.
Storage adds a from method, enabled by installing iceberg-js.
Realtime user broadcast push now supports metadata.
Adds the isdistinct and regex pattern matching operators for PostgREST queries.
Adds an endpoint for listing OAuth grants.
Adds an endpoint for revoking OAuth grants.
Functions requests support a configurable timeout.
Auth supports throwing errors instead of returning them.
Adds support for paginating and sorting buckets.
Adds API calls for managing OAuth 2.1 authorization consent.
Adds support for updating OAuth clients.
Adds an explicit REST call for Realtime.
Adds storage vectors and analytics in storage-js.
Behavior and default changes 5
Forwards options.mediation to navigator.credentials.get in signInWithPasskey.
PKCE verifiers are stored in per-flow slots so they survive overlapping flows.
httpSend can send binary payloads.
PostgREST now automatically retries transient errors.
PostgREST adds timeout protection for requests.
Tooling 1
postgrest-typegen output resolves no-argument rpc overloads.
Fixes and other changes 168
Functions now send a Blob or File with its own content type.
Storage now sends multipart fields before files.
The PostgREST retry guard treats TimeoutError as an abort.
Avoids instantiation depth errors for large relationship unions.
Returns the stored session when a refresh loses to another tab.
Silences a commit-guard-discarded refresh during initial session handling.
Drops the legacy prefix from lifecycles.
Warns when schema is passed outside db options.
Storage object versioning was updated; the notes do not specify the details.
An unverified factor is unenrolled after registration fails.
Converts a stolen-lock AbortError when acquireTimeout is 0.
Warns when the deprecated lock option is used.
Uses the custom logger for the warning when send() falls back to REST.
Prevents an unhandled rejection during refresh.
Trace context headers are added to the canonical CORS allow-list, so they are allowed by CORS.
Trace propagation sampling and diagnostics are improved.
Prevents duplicate on bindings in realtime.
Clears stale join payload on sign-out.
Auth preserves the error message for 5xx errors.
Calling setAuth no longer disables token refresh.
The return type mismatch for createSignedUrls is resolved.
The db retry option is now forwarded.
throwOnError is now honoured when maybeSingle finds multiple rows.
StorageApiError now exposes the service error code.
UUID validation now accepts uppercase UUIDs.
Realtime now preserves presence refs.
Console noise from stale refresh tokens is downgraded.
Aborted and transient fetch failures are logged with console.warn instead of console.error.
Object keys are URL-encoded in CDN purge methods.
Response Content-Type matching is case-insensitive.
The Node warning is skipped when running in Deno.
The cross-signal abort listener is cleaned up when invoke returns.
Auth is now set when the INITIAL_SESSION event is triggered.
Fixed a Realtime presence issue.
Corrected PostgREST self-reference inference.
Self-referencing embeds are now type hinted as arrays.
track() now forwards opts to send().
Unrecognized sb_ API key subtypes now produce a warning instead of throwing.
Avoids an edge runtime warning.
Function calls no longer send the API key in the Authorization header.
Broadcast header fields are encoded as UTF-8.
Preserves the PKCE verifier during auth flows.
Local session is now cleared when signout fails.
Init-time notifications are deferred until initializePromise resolves.
Disconnected status is suppressed for onHeartbeat consumers.
Functions now honor a caller's Content-Type override regardless of casing.
Storage list() keeps sortBy defaults when passed a partial sortBy.
Preserves a valid session when refresh fails and cools down repeated failures.
Fixes PostgREST then typing.
AuthApiError instances already returned through the contract are no longer logged with console.error.
Request headers are passed as a plain object for React Native and custom-fetch compatibility.
For expired JWTs, getClaims returns AuthInvalidJwtError.
The implicit grant gate recognizes redirects containing ?error=.
PostgREST returns a structured error when a successful response has a non-JSON body.
Adds a react-native export condition for Hermes-safe resolution.
Restores the signup user response.
Client IDs are encoded in OAuth requests.
StreamDownloadBuilder implements Promise and memoizes its executor.
For email_change single-confirmation verification, verifyOtp now returns a null user and session.
Restores detection of aborts represented by non-Error values in the fetch catch handler.
Returns null when JSON parsing fails.
Guards sessionStorage access in browsers with restricted storage.
The CustomProvider type was narrowed to fix downstream consumer typechecking.
The OAuth type was narrowed to fix downstream consumer typechecking.
Enum-like unions are widened with (string & {}) for forward compatibility, allowing additional string values.
The insert and upsert signatures are unified, making their API signatures consistent.
The auth client now forwards lockAcquireTimeout to SupabaseAuthClient, so the configured timeout can take effect.
WebAuthnError gains toJSON for correct JSON serialization.
Transport-level CHANNEL_ERROR now surfaces a real Error.
Fixes a regression in query reassignment.
Narrows column types after a not(column, is, null) filter.
Applies metadata, headers, and cacheControl deduplication to signed URL uploads.
Forwards the duplex option for stream uploads through uploadToSignedUrl.
Custom fetch is now propagated to the realtime client.
PKCE recovery flows now emit the PASSWORD_RECOVERY event.
The signedUrl type now allows null in createSignedUrls.
Realtime now throws Error objects instead of bare strings.
Cloudflare error codes are now included in NETWORK_ERROR_CODES.
The Prettify wrapper was removed from exported types for TypeDoc expansion.
Client-side normalization of signed URL render endpoints was removed.
Explicit return types were added to toJSON methods for JSR compatibility.
The empty transform check is now applied to download.
The empty transform check is now applied to getPublicUrl.
RPC calls now handle bigint values.
AuthError now implements toJSON for correct JSON serialization.
StorageError now implements toJSON for correct JSON serialization.
Fixes type inference for isNotNullable and SETOF scalar computed columns.
Adds toJSON to FunctionsError for correct JSON serialization.
Vector requests no longer send duplicate content-type headers.
Excess properties are now rejected in insert, update, and upsert.
Missing-session messages are logged with console.warn instead of console.error.
PostgrestError now implements toJSON for correct JSON serialization.
Excess properties are now rejected in insert, update, and upsert.
Uploads now set the correct content-type.
Excess properties are now rejected in insert, update, and upsert.
Storage types now support TypeScript projects using exactOptionalPropertyTypes.
Prevents Args: never functions from being classified as computed fields.
Adds type safety for column names passed to eq() and neq().
Fixes maybeSingle for all request methods by removing the Accept header override.
Spreads all DEFAULT_FILE_OPTIONS in uploadToSignedUrl.
The vsn type is reverted to string, affecting TypeScript types for realtime.
Structural detection in json() recognizes Response-like errors.
Guards lock stealing against cascading when another request steals the lock.
Signed URLs are no longer rewritten to the render endpoint when the transform object is empty.
Improves FileObject type accuracy by making fields nullable where appropriate.
Realtime patches channel join payloads with the resolved access token before flushing the send buffer.
Auth can recover from orphaned navigator locks using a steal fallback.
Resolves Firefox content script Promise.then() security errors in locks.
Enforces type safety for table and view names passed to from().
Fixes removeChannel when unsubscribe succeeds.
OAuth authorization types now match API responses, improving type accuracy for authorization flows.
Vector operations now handle empty 200 responses.
Fixed fallback naming in auth WebAuthn handling.
Reverts the client platform and runtime detection headers.
Reverts table-filter validation in postgres_changes event dispatch.
Handles uncaught promise rejections during initialization.
Makes environment detection safe across Node and browser runtimes.
Adds a generic overload for the postgres_changes event type.
Sends a heartbeat when the initial connection encounters an error.
Clears local storage on signOut when the session is already missing.
Exposes status on the StorageError base class.
Exposes statusCode on the StorageError base class.
Restores SSR OAuth functionality that was broken in v2.91.0.
Subscriber notification is deferred to prevent a deadlock during exchangeCodeForSession.
Resolves a cross-context Promise error in Firefox extensions.
Validates the table filter during postgres_changes event dispatch.
Prevents shared state between query builder operations.
The user type now includes the banned_until property.
Object bodies are automatically stringified when a custom Content-Type header is provided.
The factor type now includes the last_challenged_at property.
The session is preserved when a magic link is clicked twice.
RPC HEAD requests with object arguments use POST with return minimal.
The authorization header is omitted when no access token exists.
A websocket race condition in Node.js is now handled.
Resolves ESM import failures on jsDelivr by adding .js extensions.
A helpful error is now provided when the PKCE code verifier is missing.
The web worker is terminated on disconnect to prevent a memory leak.
Custom JWT tokens are preserved across channel resubscribe.
The auth client skips the navigator lock when persistSession is false.
Postgres changes filter comparison handles null values.
Corrects QueryVectorsResponse to use vectors instead of matches.
Keeps the code verifier in storage during edge cases.
Adds an ESM wrapper to resolve a module-not-found error in Nuxt.
Suppresses the getSession warning when getUser is called first.
Fixes setof type inference for cross-schema RPC calls.
Minor fixes were made to OAuth types.
Validates empty or invalid relation names in Postgrest.
Fixes the storage analytics bucket property.
PostgREST errors now bubble up fetch error causes and codes.
Realtime message encoding now accounts for null refs.
Callback IDs use Symbols to resolve compatibility with Next.js 16.
Calling setAuth is not required when using a custom JWT token.
signInWithSSO now performs an automatic browser redirect.
Registration and authentication use direct attestation.
Abort and timeout errors are normalized as FunctionsFetchError.
The UserAppMetadata interface gains a providers type.
The webauthn parameter is optional, and registration parameters are moved to webauthn.
Adds TypeScript types for documented JWT claims fields.
Warnings are emitted only if multiple clients share a storage-key.
Moves the session warning proxy from the session to the user object.
Removes redirection from getAuthorizationDetails.
Handles 204 No Content responses when deleting an OAuth client.
Adds support for the incoming PostgreSQL major version 14.
Fixes a missing request body when the developer supplies a Content-Type header.
Adds application/pdf response parsing.
Corrects list v2 types to match the data returned by the API.
Enhances the RealtimeChannel type.
Uses a backward-compatible return type in the download function.