Contributing to Supabase JS Libraries

Thank you for your interest in contributing to the Supabase JavaScript SDK! This guide will help you get started with contributing to the Supabase JS monorepo.

📋 Table of Contents

• Getting Started
• Development Workflow
• Commit Guidelines
• Pull Request Process
• Testing
• Documentation
• Release Process
• Getting Help

Getting Started

Prerequisites

• Node.js (version 20 or higher)
• pnpm (enable via corepack enable — the workspace pins the version in package.json)
• Docker (required for integration tests)
• Git

Initial Setup

1. Fork the repository on GitHub

2. Clone your fork locally:

   git clone git@github.com:YOUR_USERNAME/supabase-js.git
   cd supabase-js
   

3. Install dependencies:

   corepack enable
   pnpm install
   

4. Build all packages:

   pnpm nx run-many --target=build --all
   

5. Run tests to ensure everything works:

   pnpm nx affected --target=test
   

Browser tests (optional)

The test:integration:browser target for supabase-js uses Puppeteer. The workspace denies arbitrary install scripts by default, so Puppeteer does not download Chromium during pnpm install. If you want to run browser tests locally, install Chrome once:

pnpm exec puppeteer browsers install chrome

CI does this explicitly after pnpm install, so it's only a manual step for local browser testing.

Development Workflow

Making Changes

1. Create a new branch from master (the default branch — features, fixes, and chores all start here). Branch from v3 only when working on v3-only breaking changes:

   git checkout master
   git pull upstream master
   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bug-fix
   

   v3-only breaking changes target the v3 branch directly. The v3 branch is kept in sync with master periodically via a maintainer-run merge — no per-PR action needed from contributors.

2. Make your changes in the appropriate library under packages/core/

3. Follow our coding standards:

   • Use TypeScript for all new code
   • Follow existing code style and patterns
   • Add JSDoc comments for public APIs
   • Use meaningful commit messages (see Commit Guidelines)

4. Test your changes:

   # Run affected tests
   pnpm nx affected --target=test
   
   # Run specific library tests
   pnpm nx test <package-name>
   

   For detailed testing instructions, see TESTING.md and the README in each package directory.

5. Format your code:

   pnpm nx format
   

6. Build affected packages:

   pnpm nx affected --target=build
   

Commit Guidelines

We use Conventional Commits with automated tooling to ensure consistent commit messages and enable automatic versioning.

Using the Interactive Commit Tool

You can use the interactive commit tool instead of git commit directly:

pnpm commit

This command will:

• Guide you through creating a properly formatted commit message
• Validate your commit against our rules
• Ensure all required fields are filled out correctly
• Prevent invalid commits from being created

Commit Message Format

All commits must follow this format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Available Types

Type	Description
feat	A new feature
fix	A bug fix
docs	Documentation only changes
style	Changes that do not affect the meaning of the code
refactor	A code change that neither fixes a bug nor adds a feature
perf	A code change that improves performance
test	Adding missing tests or correcting existing tests
build	Changes that affect the build system or external dependencies
ci	Changes to our CI configuration files and scripts
chore	Other changes that don't modify src or test files
revert	Reverts a previous commit

Available Scopes

Library-Specific Scopes

• auth - Changes to @supabase/auth-js
• functions - Changes to @supabase/functions-js
• postgrest - Changes to @supabase/postgrest-js
• realtime - Changes to @supabase/realtime-js
• storage - Changes to @supabase/storage-js
• supabase - Changes to @supabase/supabase-js

Workspace-Level Scopes

• repo - Repository-level changes
• deps - Dependencies
• ci - Changes to CI
• release - Release process
• docs - Documentation
• scripts - Build/dev scripts
• misc - Miscellaneous

Commit Examples

feat(auth): add support for custom auth providers
fix(storage): resolve upload timeout issue
docs(postgrest): update filter documentation
chore(deps): update nx to latest version
ci(release): add preview package generation

Important Notes

• Scope is required - Every commit must have a scope
• Use imperative mood - "add feature" not "added feature"
• Keep subject line under 100 characters
• No period at the end of the subject line
• Use the interactive tool - pnpm commit ensures compliance

Pull Request Process

Before Submitting

1. Ensure your branch is up to date with the branch you're targeting (typically master; v3 only for v3-only breaking changes):

   git checkout <target-branch>     # master or v3
   git pull upstream <target-branch>
   git checkout your-branch
   git rebase <target-branch>
   

2. Run the full test suite:

   pnpm nx affected --target=test
   

3. Build all affected packages:

   pnpm nx affected --target=build
   

Submitting Your PR

1. Push your branch to your fork:

   git push origin your-branch-name
   

2. Create a Pull Request on GitHub with:

   • Clear title describing the change
   • Detailed description of what was changed and why
   • Reference any related issues
   • Screenshots or examples if applicable

PR Requirements

All pull requests must meet these requirements:

• ✅ At least 1 approving review from a code owner
• ✅ All status checks passing (CI/CD pipeline)
• ✅ No merge conflicts with the base branch
• ✅ Squash merge only (enforced by repository settings)

Review Process

1. Automated checks will run (linting, testing, building)
2. Code owners will be automatically requested for review
3. Address feedback by pushing new commits to your branch
4. Resolve all conversations before merge

Testing

Each package has its own testing requirements and infrastructure. For comprehensive testing information, see:

• TESTING.md - Overview of testing across all packages
• Package-specific guides - Detailed testing instructions in each package's README:
  • supabase-js
  • auth-js
  • functions-js
  • postgrest-js
  • realtime-js
  • storage-js

Quick Testing Commands

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

# Run affected tests only (recommended during development)
pnpm nx affected --target=test

# Run tests with coverage
pnpm nx test <package> --coverage

Test Requirements by Package

Package	Docker Required	Details
auth-js	✅ Yes	See README
functions-js	✅ Yes	See README
postgrest-js	✅ Yes	See README
realtime-js	❌ No	See README
storage-js	✅ Yes	See README
supabase-js	❌ No*	See README

*supabase-js integration tests require additional setup

Documentation

TypeScript API Documentation

We automatically generate TypeScript API documentation that is used by the main Supabase documentation site. The process works as follows:

1. TypeDoc generates JSON specifications from TypeScript source code
2. GitHub Actions publishes these specs to GitHub Pages after every successful stable release from master
3. Main Supabase repository uses these JSON files to generate the official API docs via make commands

Available Documentation Commands

# Generate JSON specs for all libraries (used by main docs)
pnpm nx run-many --target=docs:json --all

# Generate HTML docs for all libraries (for local viewing)
pnpm nx run-many --target=docs --all

# Generate docs for a specific library
pnpm nx docs:json auth-js
pnpm nx docs postgrest-js

Published API Specifications

When contributing changes that affect public APIs, the documentation will be automatically updated when your PR is merged.

Release Process

Fixed Version Mode

All packages in this monorepo use fixed version mode, meaning they share the same version number and are released together. This ensures compatibility and simplifies dependency management.

Testing Releases

If you need to test your changes with a release build, you can use pkg.pr.new:

1. Create a PR with your changes
2. Comment on the PR and tag a maintainer, asking them to add the trigger: preview label
3. A maintainer will add the label to trigger the preview release
4. Use the generated package URLs to test your changes in other projects

This allows you to test package changes without waiting for an official release, while ensuring preview releases are controlled by maintainers.

Official Releases

Official releases are handled by maintainers using Nx Release. You can read more in the RELEASE.md

Getting Help

Resources

• Documentation: supabase.com/docs
• Community: GitHub Discussions
• Issues: GitHub Issues
• Discord: Supabase Discord

Reporting Issues

When reporting issues, please include:

1. Clear description of the problem
2. Steps to reproduce the issue
3. Expected vs actual behavior
4. Environment information (Node.js version, library versions, etc.)
5. Code examples or minimal reproduction cases

Asking Questions

• General questions: Use GitHub Discussions
• Bug reports: Use GitHub Issues
• Feature requests: Use GitHub Issues with the "enhancement" label

🤝 Code of Conduct

We are committed to providing a welcoming and inspiring community for all. Please review our Code of Conduct before participating.

📄 License

By contributing to Supabase JS Libraries, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to Supabase! 💚