Supabase JS Client Libraries

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 client libraries:

Library	Description
@supabase/supabase-js	Main isomorphic client for Supabase
@supabase/auth-js	Authentication client
@supabase/postgrest-js	PostgREST client for database operations
@supabase/realtime-js	Real-time subscriptions client
@supabase/storage-js	File storage client
@supabase/functions-js	Edge Functions client

💡 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 Client - Authentication and user management
• Database Client - Database queries and operations
• Realtime Client - Real-time subscriptions
• Storage Client - File upload and management
• Functions Client - Edge Functions invocation
• Main Client - Combined client library

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 client
│       ├── functions-js/      # Edge Functions client
│       ├── postgrest-js/      # PostgREST database client
│       ├── realtime-js/       # Real-time subscriptions client
│       ├── storage-js/        # File storage client
│       └── supabase-js/       # Main isomorphic client
├── 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

---

Website • Documentation • Community • Twitter