Supabase JS SDK

Guides · Reference Docs

For contributors: Repository Structure Changed

This repository has been restructured as a monorepo. All libraries, including supabase-js itself, have moved to packages/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:

💡 Note for Package Users: If you install and use these packages, nothing has changed. Continue installing packages normally:

npm install @supabase/supabase-js
npm install @supabase/auth-js

The monorepo structure only affects contributors. This is how we develop and maintain the code, not how you use it.

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/supabase/supabase-js.git
cd supabase-js

# Install dependencies
npm install

# Build all packages
npx nx run-many --target=build --all

🏗️ Development

Workspace Commands

# Build a specific library
npx nx build auth-js

# Test a specific library
npx nx test postgrest-js

# Build affected projects (only build what changed)
npx nx affected --target=build

# Generate dependency graph
npx nx graph

# Format all code
npx nx format

# Check code formatting
npx nx format:check

Working with Individual Libraries

Each library can be developed independently:

# Start development with watch mode
npx nx build auth-js --watch
npx nx test auth-js --watch

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Run tests (npx nx affected --target=test)
5. Commit your changes (npm run commit)
6. Push to your branch (git push origin feature/amazing-feature)
7. 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 format before 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.

Quick examples:

# Run tests for a specific package
npx nx test <package-name>

# Run tests with coverage
npx nx test <package-name> --coverage

📚 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.

🏛️ Architecture

Monorepo Structure

supabase-js/
├── packages/
│   └── core/                  # Published libraries
│       ├── auth-js/           # Authentication sdk
│       ├── functions-js/      # Edge Functions sdk
│       ├── postgrest-js/      # PostgREST database sdk
│       ├── realtime-js/       # Real-time subscriptions sdk
│       ├── storage-js/        # File storage sdk
│       └── supabase-js/       # Main isomorphic sdk
├── nx.json                    # npx nx workspace configuration
├── package.json               # Root package.json and workspaces setup
└── ...

📄 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