@supabase/supabase-js

Isomorphic Javascript SDK for Supabase

weekly downloads10.6M

versionv2.97.0

licenseMIT

categorydatabase

javascripttypescriptsupabase

Overview

@supabase/supabase-js is an isomorphic JavaScript client library that provides a unified interface to Supabase's backend-as-a-service platform. It wraps multiple underlying SDKs—including postgrest-js for database operations, auth-js for authentication, realtime-js for subscriptions, storage-js for file management, and functions-js for serverless functions—into a single cohesive API. With over 10 million weekly downloads, it has become a popular choice for developers building full-stack JavaScript applications who want PostgreSQL database access without managing server infrastructure.

The library is designed to work across JavaScript runtimes including Node.js, browsers, Deno (via JSR), Cloudflare Workers, and React Native/Expo. It provides first-class TypeScript support with automatic type inference from your database schema, making it possible to write fully type-safe queries without manually maintaining interface definitions. The SDK handles connection pooling, authentication token management, and real-time WebSocket subscriptions transparently.

Developers choose supabase-js when they need a PostgreSQL-backed application with minimal backend setup. It's particularly appealing for teams that want to avoid configuring separate authentication systems, file storage providers, and WebSocket servers. The library uses PostgREST conventions under the hood, which means your database schema directly defines your API surface—tables become queryable endpoints, row-level security policies enforce access control, and foreign key relationships are automatically detected for typed joins.

The package exists within the broader Supabase ecosystem as an open-source alternative to Firebase, offering similar developer experience while using standard PostgreSQL instead of a proprietary database. This approach gives developers the flexibility to self-host or migrate data without vendor lock-in while maintaining the convenience of a batteries-included SDK.

Quick Start

typescript

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_ANON_KEY
);

async function todoApp() {
  const { data: { user }, error: authError } = await supabase.auth.signInWithPassword({
    email: 'user@example.com',
    password: 'secure-password'
  });

  if (authError) throw authError;

  const { data: todos, error: fetchError } = await supabase
    .from('todos')
    .select('id, title, completed, created_at')
    .eq('user_id', user.id)
    .order('created_at', { ascending: false });

  if (fetchError) throw fetchError;

  const { data: newTodo, error: insertError } = await supabase
    .from('todos')
    .insert({ title: 'Learn Supabase', completed: false, user_id: user.id })
    .select()
    .single();

  if (insertError) throw insertError;

  const channel = supabase
    .channel('todos-changes')
    .on('postgres_changes', 
      { event: '*', schema: 'public', table: 'todos', filter: `user_id=eq.${user.id}` },
      (payload) => {
        console.log('Todo changed:', payload.new);
      }
    )
    .subscribe();

  await supabase
    .from('todos')
    .update({ completed: true })
    .eq('id', newTodo.id);

  setTimeout(() => channel.unsubscribe(), 5000);
}

todoApp().catch(console.error);

Use Cases

Building SaaS applications with multi-tenant data isolation: Use row-level security policies in PostgreSQL combined with supabase-js auth to automatically filter queries based on the authenticated user. The SDK's authentication state integrates seamlessly with database policies, so you write queries without manual user ID filters—the database enforces access control.

Real-time collaborative tools: Subscribe to database changes using the real-time channels API to build features like live cursors, collaborative document editing, or dashboards that update when other users modify data. The library handles WebSocket connection management and automatic reconnection.

Mobile and web apps with offline-capable file uploads: Use the storage API to upload user-generated content like profile pictures or documents with automatic resumable uploads. Combined with the database API, you can store file metadata and enforce access policies that mirror your data permissions.

Serverless applications on edge runtimes: Deploy to Cloudflare Workers, Vercel Edge Functions, or Deno Deploy while using supabase-js to query your PostgreSQL database. The isomorphic design and custom fetch implementation support means the same code runs in Node.js during development and edge runtimes in production.

Rapid prototyping and MVPs: Spin up authentication (email/password, OAuth, magic links), a PostgreSQL database with a type-safe query builder, and file storage without configuring separate services. The unified SDK reduces the number of dependencies and integration points you need to manage during early development.

Pros & Cons

Pros

+Unified API for database, auth, storage, and real-time features reduces integration complexity and dependency count compared to assembling separate libraries
+Excellent TypeScript support with automatic type generation from database schemas enables type-safe queries without manual type maintenance
+Isomorphic design works across Node.js, browsers, Deno, edge runtimes, and React Native with minimal configuration differences
+Built on PostgreSQL and open protocols (PostgREST, WebSockets) means you can self-host or migrate away without rewriting application code
+Row-level security policies in the database layer provide security enforcement that can't be bypassed by client-side code manipulation

Cons

−Tight coupling to Supabase platform means some features require a Supabase project even if self-hosting PostgreSQL elsewhere
−Real-time subscriptions consume database connections and have scaling limitations compared to dedicated message queue systems for high-volume events
−Limited query flexibility compared to raw SQL or ORMs like Prisma—complex joins, subqueries, and aggregations often require RPC functions or raw queries
−Bundle size is larger than specialized alternatives since it includes all services even if you only need database access
−Breaking changes between v1 and v2 required significant migration effort, and the ecosystem's relative youth means API stability is still evolving

Alternatives

prismav7.4.0

Prisma is an open-source database toolkit. It includes a JavaScript/TypeScript ORM for Node.js, migrations and a modern GUI to view and edit the data in your database. You can use Prisma in new projects or add it to an existing one.

databaseCLIORM

7.8M / week

Install

bash

npm install @supabase/supabase-js

bash

pnpm add @supabase/supabase-js

bash

bun add @supabase/supabase-js

Overview

Quick Start

typescript

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_ANON_KEY
);

async function todoApp() {
  const { data: { user }, error: authError } = await supabase.auth.signInWithPassword({
    email: 'user@example.com',
    password: 'secure-password'
  });

  if (authError) throw authError;

  const { data: todos, error: fetchError } = await supabase
    .from('todos')
    .select('id, title, completed, created_at')
    .eq('user_id', user.id)
    .order('created_at', { ascending: false });

  if (fetchError) throw fetchError;

  const { data: newTodo, error: insertError } = await supabase
    .from('todos')
    .insert({ title: 'Learn Supabase', completed: false, user_id: user.id })
    .select()
    .single();

  if (insertError) throw insertError;

  const channel = supabase
    .channel('todos-changes')
    .on('postgres_changes', 
      { event: '*', schema: 'public', table: 'todos', filter: `user_id=eq.${user.id}` },
      (payload) => {
        console.log('Todo changed:', payload.new);
      }
    )
    .subscribe();

  await supabase
    .from('todos')
    .update({ completed: true })
    .eq('id', newTodo.id);

  setTimeout(() => channel.unsubscribe(), 5000);
}

todoApp().catch(console.error);

Use Cases

Pros & Cons

Pros

+Unified API for database, auth, storage, and real-time features reduces integration complexity and dependency count compared to assembling separate libraries
+Excellent TypeScript support with automatic type generation from database schemas enables type-safe queries without manual type maintenance
+Isomorphic design works across Node.js, browsers, Deno, edge runtimes, and React Native with minimal configuration differences
+Built on PostgreSQL and open protocols (PostgREST, WebSockets) means you can self-host or migrate away without rewriting application code
+Row-level security policies in the database layer provide security enforcement that can't be bypassed by client-side code manipulation

Cons

−Tight coupling to Supabase platform means some features require a Supabase project even if self-hosting PostgreSQL elsewhere
−Real-time subscriptions consume database connections and have scaling limitations compared to dedicated message queue systems for high-volume events
−Limited query flexibility compared to raw SQL or ORMs like Prisma—complex joins, subqueries, and aggregations often require RPC functions or raw queries
−Bundle size is larger than specialized alternatives since it includes all services even if you only need database access
−Breaking changes between v1 and v2 required significant migration effort, and the ecosystem's relative youth means API stability is still evolving