supabase-js

supabase-js is the official isomorphic JavaScript client for Supabase, the open-source Firebase alternative built on Postgres. A single createClient call gives you a typed gateway to your entire backend: query and mutate your Postgres database through PostgREST, authenticate and manage users, subscribe to realtime database changes over WebSockets, upload and download files, and invoke edge functions.

The package composes five focused sub-libraries (auth-js, postgrest-js, realtime-js, storage-js, and functions-js) behind one ergonomic, fully typed surface. It runs anywhere JavaScript runs — Node.js, Deno, Bun, browsers, and React Native — and can generate end-to-end types from your database schema so queries are checked at compile time.

What You Get

• A single typed createClient client that exposes database, auth, realtime, storage, and edge-function APIs
• A chainable PostgREST query builder (.from().select().eq()...) with generated TypeScript types from your schema
• Built-in authentication and session management with support for email, OAuth, magic links, and more
• Realtime subscriptions to Postgres changes and broadcast/presence channels over WebSockets
• Isomorphic support across Node.js, Deno, Bun, browsers, and React Native

Common Use Cases

• Building full-stack web and mobile apps backed by a hosted Supabase Postgres database
• Adding authentication and row-level-secured data access to a frontend without a custom backend
• Streaming live data into a UI via realtime subscriptions to table changes
• Handling user file uploads and downloads through Supabase Storage
• Calling server-side logic through Supabase Edge Functions from client code

Under The Hood

Architecture — supabase-js is a thin composition layer that lives in packages/core/supabase-js/src of an Nx-managed pnpm monorepo. createClient (in index.ts) instantiates a SupabaseClient (SupabaseClient.ts) that acts as a facade, constructing and holding five specialized sub-clients — SupabaseAuthClient (extending auth-js), PostgrestClient from postgrest-js, RealtimeClient from realtime-js, StorageClient from storage-js, and FunctionsClient from functions-js — and wiring them together with a shared authenticated fetch (lib/fetch.ts) plus resolved defaults from lib/constants.ts and lib/helpers.ts. Calls like .from(), .auth, .channel(), .storage, and .functions are delegated straight to the relevant sub-client.

Tech Stack — Written in TypeScript (~5.8) and published as dual CJS/ESM with generated .d.ts types. Its runtime dependencies are the five @supabase/* sub-packages consumed as workspace references; there are no other production dependencies, and it relies on the platform’s native fetch and WebSocket APIs for isomorphism. Tooling is Nx 22 for the monorepo, Vite/Vitest and Jest for tests, ESLint + Prettier + Husky + commitlint for quality gates, and pnpm as the package manager.

Code Quality — Testing is thorough and multi-runtime: test/ contains unit tests, integration tests, browser (integration.browser.test.ts) and Deno suites, plus dedicated module-resolution and Hermes/React-Native bundle-compatibility checks that assert the package resolves correctly under CJS, ESM, and various bundlers. Types are strict and heavily generic — the SupabaseClient/createClient signatures thread a Database schema type through to compile-time-checked queries — and conventional-commit enforcement keeps the changelog automated.

API Design — The developer experience is a core strength: a single createClient(url, key) returns one object from which every capability hangs via readable, chainable calls (supabase.from('profiles').select('*')). Naming is consistent across sub-clients, the schema-driven generics give autocomplete and type-safety without boilerplate, and getting started requires only two arguments. Extensive official guides and reference docs back the API up.