supabase-js: the isomorphic client behind a Postgres-first backend

What supabase-js actually removes from your stack

A Supabase project exposes Postgres through PostgREST, authentication through GoTrue, file storage through a storage service, and pub/sub through Realtime. Each of those is reachable over plain HTTP or WebSocket, but each has its own endpoint shape, headers and error format. supabase-js exists to collapse that into one object you construct once and pass around. The README describes the repository as a monorepo containing the complete suite of Supabase JavaScript SDK, with @supabase/supabase-js as the main isomorphic SDK and separate packages for auth, PostgREST, realtime, storage and functions. The target reader is a frontend or full-stack JavaScript developer who wants a Postgres database with auth and file storage attached, without writing a server tier first. The word isomorphic in the description is doing real work: the same import is meant to run in a browser tab, in a Node.js process, in Deno, in Bun, in React Native and in a Cloudflare Worker.

One client object, six packages, and PostgREST underneath

The architecture is a facade. @supabase/supabase-js sits on top of @supabase/postgrest-js, @supabase/auth-js, @supabase/realtime-js, @supabase/storage-js and @supabase/functions-js, and the main package re-exports their behaviour behind namespaces. Database queries do not speak SQL over a socket. They build a PostgREST request, and PostgREST translates it into SQL against your Postgres instance. That is why the client supports filtering, ordering, embedding related rows and calling stored procedures via rpc rather than exposing a query planner. Realtime subscriptions run over WebSocket, which is why the README states that browsers using realtime features must support the native WebSocket API, on top of the native fetch API required for everything else. The data flow for a normal read is: client method call, PostgREST HTTP request with your project URL and key, SQL execution, JSON response. There is no local query engine and no client-side cache.

Installing supabase-js and running a first insert

The README gives one installation command, and it is the same package for every runtime it supports.

npm install @supabase/supabase-js

That is the only install step the README documents. For wiring the client to a project, it points to the guides and the JavaScript reference docs rather than inlining an example, so the configuration values live there. The repository layout shows the SDK split across packages/core/supabase-js, packages/core/auth-js, packages/core/postgrest-js, packages/core/realtime-js, packages/core/storage-js and packages/core/functions-js, and each package has its own README with the API surface for that namespace. The pattern to notice when you read those docs is that the client returns a result object with data and error rather than throwing. If you are used to try/catch around every call, that is a habit you have to unlearn here. The repository does not document a rollback path for a partially applied multi-statement write, because each call is a separate PostgREST request.

The runtime support policy is the sharpest edge in the repository

This is where supabase-js differs from most client libraries, and where teams get surprised. The README states that only Node.js versions in Active LTS or Maintenance status are supported, and that when a version reaches end-of-life Supabase will drop it in a minor release, and this will not be considered a breaking change. That policy is already spent: Node.js 18 support was dropped in version 2.79.0, with 2.78.0 named as the last version that supported it, and Node.js 20 support was dropped in version 2.110.0, with 2.109.0 named as the last version. Deno, Bun, React Native and Cloudflare Workers are supported on current stable versions with the same minor-release caveat, and those runtimes do not publish a schedule as structured as Node.js. If you pin a caret range and your CI image is on an old Node.js line, a routine dependency bump can take you from working to unsupported without a major version change. Pin exactly, and read the release notes before moving.

Where supabase-js is the wrong tool

The client is a transport, not an ORM. It has no migration system, no schema definition language and no relation graph it can traverse on its own. If your team expects typed models generated from a schema, eager loading across arbitrary relation chains, or a migration diff command, supabase-js does not provide them; the codegen scripts in package.json generate types from the API surface, not from your database schema. The second limit is coupling: every database call is a PostgREST call, so anything PostgREST cannot express is either an rpc call to a Postgres function or a request that leaves the client entirely. The third is that the SDK assumes a Supabase-hosted or self-hosted Supabase project with the REST, auth and realtime services in place. Pointing it at a bare Postgres instance will not work. Finally, the README flags that experimental features may be removed or changed without notice, so anything labelled experimental should not sit under a production write path.

supabase-js versus Prisma and Drizzle

The comparison that matters is not feature count, it is where the query is built. Prisma and Drizzle both put a schema definition in your repository and generate a typed client from it, so the database shape is versioned alongside your application code and migrations are part of the same tool. supabase-js does the opposite: it assumes the database already exists and that PostgREST will describe it, so there is nothing to generate from your side and nothing to migrate. That makes supabase-js faster to start and weaker at schema evolution. Drizzle in particular emits SQL you can read, which matters when a query is slow and you need to understand the plan. With supabase-js, the SQL is produced by PostgREST, and your debugging surface is the HTTP request and the Postgres log. If you already run Supabase and your schema changes rarely, the client is the shorter path. If your schema is the thing under active development, an ORM with migrations is the better fit, and you can still keep Supabase for auth and storage.

Maintenance, release cadence and the MIT licence

The repository is not archived, and the last push was on 2026-09-22. The most recent release listed is v2.117.0 on 2026-09-22, with two canary builds on 2026-09-17 and 2026-09-22, so canary and stable are being cut from the same tree within days of each other. The upgrade cost is concentrated in runtime support rather than API churn: the version-to-Node.js mapping is the thing to track, and the README names the exact last-good versions. The monorepo uses pnpm workspaces with Nx, and package.json sets packageManager to [email protected], so contributing or building from source means matching that toolchain. The licence is MIT, which is permissive and imposes no copyleft obligation on your application; the LICENSE file is at the repository root. That is a statement about the licence text, not advice about your situation, and the SDK's licence does not govern the Supabase services you connect it to.

Editorial conclusion

Adopt supabase-js if your data already lives in Supabase Postgres and you want auth, realtime and storage through one client, or if you are shipping to browsers, Node.js, Deno, Bun, React Native or Cloudflare Workers from a single codebase. Do not adopt it if you need ORM-level migration tooling, a schema-first type generator that works offline, or a database you do not control. Before wiring anything, check the Node.js version in .nvmrc and the release notes for the last version that supported your runtime, because dropping an end-of-life Node.js line happens in a minor release and is not treated as breaking.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. supabase/supabase-js on GitHub