supabase-js
An isomorphic Javascript client for Supabase. Query your Supabase database, subscribe to realtime events, upload and download files, browse typescript examples, invoke postgres functions via rpc, invoke supabase edge functions, query pgvector.
Top Related Projects
Next-generation ORM for Node.js & TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB
A query builder for PostgreSQL, MySQL, CockroachDB, SQL Server, SQLite3 and Oracle, designed to be flexible, portable, and fun to use.
Feature-rich ORM for modern Node.js and TypeScript, it supports PostgreSQL (with JSON and JSONB support), MySQL, MariaDB, SQLite, MS SQL Server, Snowflake, Oracle DB (v6), DB2 and DB2 for IBM i.
ORM for TypeScript and JavaScript. Supports MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, SAP Hana, WebSQL databases. Works in NodeJS, Browser, Ionic, Cordova and Electron platforms.
TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.
A simple Node.js ORM for PostgreSQL, MySQL and SQLite3 built on top of Knex.js
Quick Overview
Supabase-js is the official JavaScript client library for Supabase, an open-source Firebase alternative. It provides a powerful and easy-to-use interface for interacting with Supabase's features, including real-time database, authentication, storage, and more, all within a single JavaScript package.
Pros
- Comprehensive API covering all Supabase features
- Real-time subscriptions and database listeners
- TypeScript support for improved type safety
- Seamless integration with Supabase's backend services
Cons
- Learning curve for developers new to Supabase ecosystem
- Dependency on Supabase backend services
- Limited offline support
- Potential performance overhead for large-scale applications
Code Examples
- Initializing Supabase client:
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://your-project-url.supabase.co', 'your-anon-key')
- Fetching data from a table:
const { data, error } = await supabase
.from('users')
.select('id, name, email')
.eq('active', true)
- Real-time subscription:
const subscription = supabase
.from('messages')
.on('INSERT', payload => {
console.log('New message:', payload.new)
})
.subscribe()
- File upload to storage:
const { data, error } = await supabase
.storage
.from('avatars')
.upload('public/avatar1.png', file)
Getting Started
- Install the package:
npm install @supabase/supabase-js
- Initialize the Supabase client in your application:
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://your-project-url.supabase.co', 'your-anon-key')
- Use the client to interact with Supabase services:
// Example: Fetch data from a table
const { data, error } = await supabase
.from('your_table')
.select('*')
if (error) console.error('Error:', error)
else console.log('Data:', data)
Competitor Comparisons
Next-generation ORM for Node.js & TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB
Pros of Prisma
- More robust ORM features with advanced querying capabilities
- Supports multiple databases (PostgreSQL, MySQL, SQLite, etc.)
- Strong type safety and auto-generated TypeScript types
Cons of Prisma
- Steeper learning curve, especially for complex schemas
- Requires additional setup and configuration
- Less integrated with real-time features out of the box
Code Comparison
Prisma query example:
const users = await prisma.user.findMany({
where: { age: { gte: 18 } },
include: { posts: true }
});
Supabase query example:
const { data: users, error } = await supabase
.from('users')
.select('*, posts(*)')
.gte('age', 18);
Both Prisma and Supabase-js are powerful tools for working with databases in JavaScript/TypeScript applications. Prisma offers a more traditional ORM approach with support for multiple databases, while Supabase-js provides a simpler API specifically designed for Supabase's PostgreSQL-based backend.
Prisma excels in complex data modeling and type safety, making it suitable for large-scale applications with intricate database schemas. Supabase-js, on the other hand, offers a more streamlined experience with built-in real-time capabilities and easier integration with Supabase's other features like authentication and storage.
The choice between the two depends on your project requirements, database preferences, and desired level of abstraction when working with data.
A query builder for PostgreSQL, MySQL, CockroachDB, SQL Server, SQLite3 and Oracle, designed to be flexible, portable, and fun to use.
Pros of Knex
- More flexible and database-agnostic, supporting multiple SQL databases
- Provides a powerful query builder with a chainable API
- Offers advanced features like migrations and seeds for database schema management
Cons of Knex
- Requires more setup and configuration compared to Supabase-js
- Lacks built-in real-time capabilities and authentication features
- May have a steeper learning curve for beginners
Code Comparison
Knex query example:
knex('users')
.where('age', '>', 18)
.orderBy('name', 'desc')
.limit(10)
Supabase-js query example:
supabase
.from('users')
.select('*')
.gt('age', 18)
.order('name', { ascending: false })
.limit(10)
Both libraries provide a fluent interface for querying databases, but Knex offers more flexibility across different database systems, while Supabase-js is tailored specifically for Supabase and PostgreSQL. Knex requires more setup but provides greater control over database operations, whereas Supabase-js offers a simpler, more opinionated approach with additional features like real-time subscriptions and built-in authentication.
Feature-rich ORM for modern Node.js and TypeScript, it supports PostgreSQL (with JSON and JSONB support), MySQL, MariaDB, SQLite, MS SQL Server, Snowflake, Oracle DB (v6), DB2 and DB2 for IBM i.
Pros of Sequelize
- Mature and well-established ORM with extensive documentation and community support
- Supports multiple database systems (MySQL, PostgreSQL, SQLite, etc.)
- Provides powerful migration and seeding tools for database management
Cons of Sequelize
- Steeper learning curve due to its comprehensive feature set
- Can be slower for complex queries compared to raw SQL
- Requires more setup and configuration compared to Supabase.js
Code Comparison
Sequelize:
const User = sequelize.define('User', {
name: DataTypes.STRING,
email: DataTypes.STRING
});
const users = await User.findAll();
Supabase.js:
const { data: users, error } = await supabase
.from('users')
.select('name, email');
Sequelize offers a more traditional ORM approach with model definitions and method-based querying, while Supabase.js provides a simpler, more declarative API for database operations. Sequelize's approach may be more familiar to developers coming from other ORMs, but Supabase.js can be quicker to get started with for simple use cases.
Sequelize excels in scenarios requiring complex data modeling and migrations, whereas Supabase.js shines in rapid development and real-time data synchronization. The choice between the two depends on project requirements, team expertise, and the desired level of abstraction from the underlying database.
ORM for TypeScript and JavaScript. Supports MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, SAP Hana, WebSQL databases. Works in NodeJS, Browser, Ionic, Cordova and Electron platforms.
Pros of TypeORM
- More mature and established ORM with a larger community and ecosystem
- Supports multiple database systems, offering greater flexibility
- Provides advanced features like migrations, relations, and caching
Cons of TypeORM
- Steeper learning curve due to its extensive feature set
- Requires more setup and configuration compared to Supabase.js
- Can be overkill for simple projects or when working with a single database
Code Comparison
TypeORM:
import { Entity, PrimaryGeneratedColumn, Column } from "typeorm"
@Entity()
export class User {
@PrimaryGeneratedColumn()
id: number
@Column()
name: string
}
Supabase.js:
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('YOUR_SUPABASE_URL', 'YOUR_SUPABASE_KEY')
const { data, error } = await supabase
.from('users')
.select('id, name')
TypeORM offers a more traditional ORM approach with decorators and entity definitions, while Supabase.js provides a simpler, API-like interface for database operations. TypeORM is better suited for complex applications with multiple databases, while Supabase.js excels in rapid development and simplicity, especially when working with Supabase's backend-as-a-service platform.
TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.
Pros of MikroORM
- Supports multiple databases (SQL, MongoDB, etc.) while Supabase-js is primarily for PostgreSQL
- Offers more advanced ORM features like lazy loading and identity map
- Provides a CLI tool for database migrations and schema management
Cons of MikroORM
- Steeper learning curve compared to Supabase-js's simpler API
- Requires more setup and configuration
- Less integrated with real-time features and authentication
Code Comparison
MikroORM:
@Entity()
export class Book {
@PrimaryKey()
id!: number;
@Property()
title!: string;
}
const orm = await MikroORM.init(config);
const book = orm.em.create(Book, { title: 'My Book' });
await orm.em.persistAndFlush(book);
Supabase-js:
const { data, error } = await supabase
.from('books')
.insert({ title: 'My Book' })
.select();
MikroORM offers more control over entity definitions and relationships, while Supabase-js provides a simpler, more straightforward API for database operations. MikroORM is better suited for complex applications with intricate data models, while Supabase-js excels in rapid development and real-time features.
A simple Node.js ORM for PostgreSQL, MySQL and SQLite3 built on top of Knex.js
Pros of Bookshelf
- More mature and established ORM with a longer history
- Offers a wider range of database support beyond PostgreSQL
- Provides more granular control over database operations and queries
Cons of Bookshelf
- Steeper learning curve compared to Supabase-js
- Requires more boilerplate code for setup and configuration
- Less integrated with modern cloud-based database solutions
Code Comparison
Bookshelf:
const user = await new User({id: 1}).fetch();
const posts = await user.related('posts').fetch();
Supabase-js:
const { data: user } = await supabase
.from('users')
.select('*, posts(*)')
.eq('id', 1)
.single();
Summary
Bookshelf is a more traditional ORM offering greater flexibility and control, while Supabase-js provides a simpler, more modern approach with tighter integration to cloud services. Bookshelf excels in complex database operations and supports multiple databases, but requires more setup. Supabase-js offers a more streamlined experience, particularly for PostgreSQL-based projects, but may be less suitable for highly customized database interactions.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Supabase JS SDK
For contributors: Repository Structure Changed
This repository has been restructured as a monorepo. All libraries, including
supabase-jsitself, have moved topackages/core/:
What You're Looking For Where It Is Now Main supabase-js code packages/core/supabase-js/Other libraries packages/core/*/Read the Migration Guide to learn more.
ð¦ Libraries
This monorepo contains the complete suite of Supabase JavaScript SDK:
| Library | Description |
|---|---|
| @supabase/supabase-js | Main isomorphic SDK for Supabase |
| @supabase/auth-js | Authentication SDK |
| @supabase/postgrest-js | PostgREST SDK for database operations |
| @supabase/realtime-js | Real-time subscriptions SDK |
| @supabase/storage-js | File storage SDK |
| @supabase/functions-js | Edge Functions SDK |
Support Policy
This section outlines the scope of support for various runtime environments in Supabase JavaScript client.
Node.js
We only support Node.js versions that are in Active LTS or Maintenance status as defined by the official Node.js release schedule. This means we support versions that are currently receiving long-term support and critical bug fixes.
When a Node.js version reaches end-of-life and is no longer in Active LTS or Maintenance status, Supabase will drop it in a minor release, and this won't be considered a breaking change.
â ï¸ Node.js 18 Deprecation Notice
Node.js 18 reached end-of-life on April 30, 2025. As announced in our deprecation notice, support for Node.js 18 was dropped in version
2.79.0.If you must use Node.js 18, please use version
2.78.0, which is the last version that supported Node.js 18.
Deno
We support Deno versions that are currently receiving active development and security updates. We follow the official Deno release schedule and only support versions from the stable and lts release channels.
When a Deno version reaches end-of-life and is no longer receiving security updates, Supabase will drop it in a minor release, and this won't be considered a breaking change.
Browsers
All modern browsers are supported. We support browsers that provide native fetch API. For Realtime features, browsers must also support native WebSocket API.
Bun
We support Bun runtime environments. Bun provides native fetch support and is compatible with Node.js APIs. Since Bun does not follow a structured release schedule like Node.js or Deno, we support current stable versions of Bun and may drop support for older versions in minor releases without considering it a breaking change.
React Native
We support React Native environments with fetch polyfills provided by the framework. Since React Native does not follow a structured release schedule, we support current stable versions and may drop support for older versions in minor releases without considering it a breaking change.
Cloudflare Workers
We support Cloudflare Workers runtime environments. Cloudflare Workers provides native fetch support. Since Cloudflare Workers does not follow a structured release schedule, we support current stable versions and may drop support for older versions in minor releases without considering it a breaking change.
Important Notes
- Experimental features: Features marked as experimental may be removed or changed without notice
ð Quick Start
Installation
npm install @supabase/supabase-js
Read more in each package's README file.
ð¤ Contributing
We welcome contributions! Please see our Contributing Guide for details.
Quick Contribution Steps
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes and add tests
- Run tests (
npx nx affected --target=test) - Commit your changes (
npm run commit) - Push to your branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development Guidelines
- Follow conventional commits for commit messages
- Add tests for new functionality
- Update documentation for API changes
- Run
npx nx formatbefore committing - Ensure all tests pass with
npx nx affected --target=test
𧪠Testing
Testing varies per package. See the top-level TESTING.md for an overview and links to package-specific guides.
ð Documentation
API Documentation
- Auth SDK - Authentication and user management
- Database SDK - Database queries and operations
- Realtime SDK - Real-time subscriptions
- Storage SDK - File upload and management
- Functions SDK - Edge Functions invocation
- Main SDK - Combined SDK
Architecture Documentation
- Contributing - Development guidelines
- Release Workflows - Release and publishing process
- Migration Guide - Migrating to the monorepo structure
- Security Policy - Security guidelines and reporting
ð Verifying provenance attestations
You can verify registry signatures and provenance attestations for installed packages using the npm CLI:
npm audit signatures
Quick example for a single package install:
npm install @supabase/auth-js
npm audit signatures
Example output:
audited 1 package in 0s
1 package has a verified registry signature
Because provenance attestations are a new capability, security features may evolve over time. Ensure you are using the latest npm CLI to verify attestation signatures reliably. This may require updating npm beyond the version bundled with Node.js.
ð License
This project is licensed under the MIT License - see the LICENSE file for details.
ð Support
- Documentation: supabase.com/docs
- Community: GitHub Discussions
- Issues: GitHub Issues
- Discord: Supabase Discord
Website ⢠Documentation ⢠Community ⢠Twitter
Top Related Projects
Next-generation ORM for Node.js & TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB
A query builder for PostgreSQL, MySQL, CockroachDB, SQL Server, SQLite3 and Oracle, designed to be flexible, portable, and fun to use.
Feature-rich ORM for modern Node.js and TypeScript, it supports PostgreSQL (with JSON and JSONB support), MySQL, MariaDB, SQLite, MS SQL Server, Snowflake, Oracle DB (v6), DB2 and DB2 for IBM i.
ORM for TypeScript and JavaScript. Supports MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, SAP Hana, WebSQL databases. Works in NodeJS, Browser, Ionic, Cordova and Electron platforms.
TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.
A simple Node.js ORM for PostgreSQL, MySQL and SQLite3 built on top of Knex.js
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot