Supabase JS SDK

The Supabase JavaScript SDK is a monorepo containing several specialized libraries. While @supabase/supabase-js is the main entry point that combines these capabilities, you can also use the individual packages:

• @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

Node.js

• Node.js 22 or later is required.
• Support for Node.js 20 was dropped in v2.110.0.
• Support for Node.js 18 was dropped on October 31, 2025.

Browsers

• All modern browsers are supported.

To use the Supabase JS SDK, install the package via npm and use createClient to establish a connection to your project using your Supabase URL and your project's public anonymous key.

npm install @supabase/supabase-js

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

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

In the Deno runtime, you can import the SDK via JSR:

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

You can access analytics functionality through the analytics property on your storage client. This works whether you are using the main @supabase/supabase-js client or a direct StorageClient from @supabase/storage-js.

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

const supabase = createClient('https://your-project.supabase.co', 'your-publishable-key')

// Access analytics operations
const analytics = supabase.storage.analytics

// Create an analytics bucket
const { data, error } = await analytics.createBucket('analytics-data')

You can run different types of tests to verify trace header propagation:

• Simple JavaScript Test (Recommended): Shows trace headers in requests clearly.
• Full TypeScript Test: Provides detailed span information.
• Real Supabase Project Test: Tests against an actual Supabase instance by providing environment variables.

Running with a Real Project

To test against your own Supabase project, export your credentials before running the simple test:

export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_KEY="your-anon-key"
node test-trace-simple.js

Edge Function calls made via supabase.functions.invoke() now separate the apikey and Authorization headers.

• The API key is sent in the apikey header.
• The Authorization header carries the signed-in user's JWT.
• For unauthenticated calls, the Authorization header no longer contains the new-format API key (sb_publishable_… or sb_secret_…). Instead, these requests rely on the apikey header.

Impacted Users: If your Edge Function code manually reads the Authorization header to extract an API key (e.g., checking for Bearer sb_...), you must update your code to read the apikey header instead. For a more robust implementation, consider migrating to @supabase/server.

You can generate and view coverage reports for supabase-js to see line, branch, and function coverage.

1. Generate the report: Run the coverage command.
2. Serve the report: Start a local server to view an interactive HTML report at http://localhost:3000.

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

# Serve coverage report locally (opens interactive HTML report)
pnpm nx serve:coverage supabase-js

You can use <script type="module"> to import the SDK as an ES module from a CDN.

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

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

Edge Functions are served on http://127.0.0.1:54321/functions/v1/<function-name>. You can view logs and test functions directly using curl.

Note: When using the Supabase CLI to get the key for headers, the CLI outputs it as ANON_KEY in the JSON status, but it is used as the SUPABASE_PUBLISHABLE_KEY for the SDK.

# View function logs
tail -f /tmp/supabase-functions.log

# Test a function directly
curl -X POST \
  -H "Authorization: Bearer $(pnpm exec supabase status --output json | jq -r '.ANON_KEY')" \
  -H "Content-Type: application/json" \
  -d '{"name":"Test"}' \
  http://127.0.0.1:54321/functions/v1/hello

Follow these steps to build the auth-js package and launch the React development server:

1. Build the library: From the repository root, install dependencies and build the auth-js package using Nx.
2. Run the example: Navigate to the React example directory, install its specific dependencies, and start the Vite development server.

# Install root dependencies and build auth-js
npm i
npx nx build auth-js

# Install the dependencies and run the example
cd example/react
npm i; npm run dev

To use the Supabase Storage SDK, install the @supabase/storage-js package via npm.

npm install @supabase/storage-js