supabase-js - Isomorphic JavaScript Client for Supabase.

• Documentation: https://supabase.com/docs/reference/javascript/start
• TypeDoc: https://supabase.github.io/supabase-js/supabase-js/v2/spec.json

Usage

First of all, you need to install the library:

npm install @supabase/supabase-js

Then you're able to import the library and establish the connection with the database:

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

// Create a single supabase client for interacting with your database
const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key')

UMD

You can use plain <script>s to import supabase-js from CDNs, like:

<script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>

or even:

<script src="https://unpkg.com/@supabase/supabase-js@2"></script>

Then you can use it from a global supabase variable:

<script>
  const { createClient } = supabase
  const _supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key')

  console.log('Supabase Instance: ', _supabase)
  // ...
</script>

ESM

You can use <script type="module"> to import supabase-js from CDNs, like:

<script type="module">
  import { createClient } from 'https://cdn.jsdelivr.net/npm/@supabase/supabase-js/+esm'
  const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key')

  console.log('Supabase Instance: ', supabase)
  // ...
</script>

Deno

You can use supabase-js in the Deno runtime via JSR:

import { createClient } from 'jsr:@supabase/supabase-js@2'

Custom fetch implementation

supabase-js uses the cross-fetch library to make HTTP requests, but an alternative fetch implementation can be provided as an option. This is most useful in environments where cross-fetch is not compatible, for instance Cloudflare Workers:

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

// Provide a custom `fetch` implementation as an option
const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
  global: {
    fetch: (...args) => fetch(...args),
  },
})

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.

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.

Important Notes

• Experimental features: Features marked as experimental may be removed or changed without notice

Development

This package is part of the Supabase JavaScript monorepo. To work on this package:

Building

# From the monorepo root
npx nx build supabase-js

# Or with watch mode for development
npx nx build supabase-js --watch

Testing

Important: The test suite includes tests for multiple runtime environments (Node.js, Deno, Bun, Expo, Next.js). Each environment has its own test runner and specific requirements.

Prerequisites for All Integration Tests

1. Docker must be installed and running
2. Supabase CLI must be installed (npm install -g supabase or via package manager)
3. Local Supabase instance must be started:

# Navigate to the supabase-js package directory
cd packages/core/supabase-js

# Start Supabase (downloads and starts all required containers)
npx supabase start

# The output will show:
# - API URL: http://127.0.0.1:54321
# - Database URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
# - Studio URL: http://127.0.0.1:54323
# - Anon key: [your-anon-key]
# - Service role key: [your-service-role-key]  # Important for some tests!

# Return to monorepo root for running tests
cd ../../..

Test Scripts Overview

| Script | Description | Requirements | | -------------------------- | ----------------------------------------- | --------------------------------------- | | test | Runs unit tests + type checking | None | | test:all | Unit + integration + browser tests | Supabase running | | test:run | Jest unit tests only | None | | test:unit | Jest unit tests in test/unit directory | None | | test:coverage | Unit tests with coverage report | None | | test:integration | Node.js integration tests | Supabase running + SERVICE_ROLE_KEY | | test:integration:browser | Browser tests using Deno + Puppeteer | Supabase running + Deno installed | | test:edge-functions | Edge Functions tests | Supabase running + Deno installed | | test:types | TypeScript type checking + JSR validation | None | | test:deno | Deno runtime compatibility tests | Supabase running + Deno installed | | test:bun | Bun runtime compatibility tests | Supabase running + Bun installed | | Expo (see section below) | React Native/Expo tests | Supabase running + dependencies updated | | Next.js (see below) | Next.js SSR tests | Supabase running + dependencies updated | | test:node:playwright | WebSocket browser tests | Supabase running + Playwright |

Unit Testing

# Run all unit tests (Jest)
npx nx test supabase-js

# Run only unit tests in test/unit directory
npx nx test:unit supabase-js

# Run tests in watch mode during development
npx nx test supabase-js --watch

# Run tests with coverage report
npx nx test:coverage supabase-js

Integration Testing

# Prerequisites: Start Supabase first (see above)

# Run Node.js integration tests
# IMPORTANT: Requires SUPABASE_SERVICE_ROLE_KEY environment variable
cd packages/core/supabase-js
export SUPABASE_SERVICE_ROLE_KEY="$(npx supabase status --output json | jq -r '.SERVICE_ROLE_KEY')"
cd ../../..
npx nx test:integration supabase-js

# Run browser-based integration tests (requires Deno)
npx nx test:integration:browser supabase-js

Running All Tests

# This runs type checking, unit tests, and integration tests sequentially
# NOTE: Will fail if Supabase is not running or dependencies not updated
npx nx test:all supabase-js

Common Issues and Solutions:

| Issue | Solution | | -------------------------------------------- | --------------------------------------------------------------- | | "Cannot find module 'https://deno.land/...'" | Deno tests incorrectly run by Jest - check jest.config.ts | | "Port 54322 already allocated" | Stop existing Supabase: npx supabase stop --project-id <name> | | "503 Service Unavailable" for Edge Functions | Supabase not running - start with npx supabase start | | "Uncommitted changes" during type check | Commit changes or add --allow-dirty to JSR publish | | Integration tests fail with auth errors | Export SUPABASE_SERVICE_ROLE_KEY (see Integration Testing) |

Platform-Specific Testing

Expo Testing (React Native)

# Prerequisites:
# 1. Supabase must be running (see Prerequisites)
# 2. Update test dependencies and pack current build
npx nx update:test-deps:expo supabase-js

# Run Expo tests from the Expo test project
cd packages/core/supabase-js/test/integration/expo
npm install
npm test
cd ../../..

Next.js Testing (SSR)

# Prerequisites:
# 1. Supabase must be running (see Prerequisites)
# 2. Update test dependencies and pack current build
npx nx update:test-deps:next supabase-js

# 3. Install Playwright browsers and dependencies
npx playwright install --with-deps

# Run Next.js tests from the Next test project
cd packages/core/supabase-js/test/integration/next
npm install --legacy-peer-deps
npm run test
cd ../../..

Deno Testing

# Prerequisites:
# 1. Deno must be installed (https://deno.land)
# 2. Supabase must be running (see Prerequisites)
# 3. Update test dependencies:
npx nx update:test-deps:deno supabase-js

# Run Deno tests
npx nx test:deno supabase-js

Edge Functions Testing

The project includes Edge Functions integration tests that require a local Supabase instance to be running.

# Prerequisites:
# 1. Ensure Docker is installed and running
# 2. Navigate to the supabase-js package directory
cd packages/core/supabase-js

# 3. Start Supabase locally (this will download and start all required containers)
npx supabase start

# Wait for the output showing all services are ready, including:
# - API URL: http://127.0.0.1:54321
# - Database URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
# - Edge Runtime container

# 4. Run the Edge Functions tests from the monorepo root
cd ../../../  # Back to monorepo root
npx nx test:edge-functions supabase-js

Important Notes:

• The Edge Functions tests will fail with 503 errors if Supabase is not running

• If you encounter port conflicts (e.g., "port 54322 already allocated"), stop any existing Supabase instances:

  npx supabase stop --project-id <project-name>
  # Or stop all Docker containers if unsure:
  docker ps | grep supabase  # List all Supabase containers
  

• The tests use the default local development credentials (anon key)

• Edge Functions are automatically served when supabase start is run

Bun Testing

# Prerequisites:
# 1. Bun must be installed (https://bun.sh)
# 2. Supabase must be running (see Prerequisites)
# 3. Update test dependencies:
npx nx update:test-deps:bun supabase-js

# Run Bun tests
npx nx test:bun supabase-js

WebSocket Browser Testing

# Prerequisites:
# 1. Supabase must be running (see Prerequisites)
# 2. Build the UMD bundle first:
npx nx build supabase-js

# Run WebSocket browser tests with Playwright
cd packages/core/supabase-js/test/integration/node-browser
npm install
cp ../../../dist/umd/supabase.js .
npm run test
cd ../../..

CI/CD Testing

When running on CI, the tests automatically use the latest dependencies from the root project. The CI pipeline:

1. Builds the main project with current dependencies
2. Creates a package archive (.tgz) with the latest versions
3. Uses this archive in Expo, Next.js, Deno, and Bun tests to ensure consistency

Updating Test Dependencies

The platform-specific tests (Expo, Next.js, Deno, Bun) use a packaged version of supabase-js rather than directly importing from source. This ensures they test the actual built package as it would be consumed by users.

How It Works

1. Build the current supabase-js package
2. Pack it into a .tgz file (like npm pack does)
3. Copy the .tgz to the test directory
4. Install it in the test project

This mimics how real users would install and use the package.

Update Scripts

# Update ALL test environment dependencies at once
# This builds, packs, and installs in all test directories
npx nx update:test-deps supabase-js

# Or update specific test environments:
npx nx update:test-deps:expo supabase-js    # Expo/React Native only
npx nx update:test-deps:next supabase-js    # Next.js only
npx nx update:test-deps:deno supabase-js    # Deno only
npx nx update:test-deps:bun supabase-js     # Bun only

When to Update:

• After making changes to the source code
• Before running platform-specific tests locally
• When debugging test failures that might be due to stale dependencies

Note: CI automatically handles this, so manual updates are only needed for local development.

Test Coverage

Viewing Coverage Reports

# Generate coverage report
npx nx test:coverage supabase-js

# Serve coverage report locally (opens interactive HTML report)
npx nx serve:coverage supabase-js
# This starts a local server at http://localhost:3000 with the coverage report

The coverage report shows:

• Line coverage
• Branch coverage
• Function coverage
• Uncovered lines with highlights

Coverage results are also automatically uploaded to Coveralls in CI for tracking over time.

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

For major changes or if you're unsure about something, please open an issue first to discuss your proposed changes.

Badges