@supabase/supabase-js

Supabase JS SDK

Isomorphic JavaScript SDK for Supabase - combining Auth, Database, Storage, Functions, and Realtime.

Guides · Reference Docs · TypeDoc

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', 'your-publishable-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', 'your-publishable-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', 'your-publishable-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 runtime's global fetch to make HTTP requests, but an alternative fetch implementation can be provided as an option. This is useful in environments where the global fetch is unavailable or where you want to customize request behavior:

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

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

Distributed Tracing with OpenTelemetry

The Supabase JS SDK can attach W3C/OpenTelemetry trace context headers (traceparent, tracestate, baggage) to outgoing requests, enabling end-to-end request tracing from your client application through Supabase services.

Trace propagation is opt-in and disabled by default. When enabled, headers are only attached to requests targeting Supabase domains (*.supabase.co, *.supabase.in, localhost).

Enable trace propagation

Opting in takes two steps: install @opentelemetry/api, and load the tracing runtime by importing the @supabase/supabase-js/tracing subpath once at your application entry point. The main bundle contains no OpenTelemetry code — the subpath import is what wires it up.

import '@supabase/supabase-js/tracing'
import { createClient } from '@supabase/supabase-js'
import { trace } from '@opentelemetry/api'

const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
  tracePropagation: true,
})

const tracer = trace.getTracer('my-app')
await tracer.startActiveSpan('fetch-users', async (span) => {
  // This request now includes the active trace context.
  const { data, error } = await supabase.from('users').select('*')
  span.end()
})

The subpath imports @opentelemetry/api directly, so module resolution fails loudly if it is not installed. If tracePropagation is enabled without the subpath import, the SDK logs a one-time warning and sends requests without trace headers; if no active context exists at request time, it silently no-ops.

Trace propagation is not available via the CDN/UMD build (https://cdn.jsdelivr.net/.../supabase.js) — there is no way to load the tracing runtime there.

Advanced configuration

interface TracePropagationOptions {
  // Enable trace propagation (default: false).
  enabled?: boolean

  // Respect upstream sampling decisions (default: true).
  // When true, headers are skipped if the upstream trace is not sampled.
  respectSamplingDecision?: boolean
}

// Always propagate, even for non-sampled traces.
const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key', {
  tracePropagation: { enabled: true, respectSamplingDecision: false },
})

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.

⚠️ Node.js 18 Deprecation Notice

Node.js 18 reached end-of-life on April 30, 2025. As announced in our deprecation notice, support for Node.js 18 was dropped in version 2.79.0.

If you must use Node.js 18, please use version 2.78.0, which is the last version that supported Node.js 18.

⚠️ Node.js 20 Deprecation Notice

Node.js 20 reached end-of-life on April 30, 2026. As announced in our deprecation notice, support for Node.js 20 was dropped in version 2.110.0.

If you must use Node.js 20, please use version 2.109.0, which is the last version that supported Node.js 20.

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.

Browsers

All modern browsers are supported. We support browsers that provide native fetch API. For Realtime features, browsers must also support native WebSocket API.

Bun

We support Bun runtime environments. Bun provides native fetch support and is compatible with Node.js APIs. Since Bun does not follow a structured release schedule like Node.js or Deno, we support current stable versions of Bun and may drop support for older versions in minor releases without considering it a breaking change.

React Native

We support React Native environments with fetch polyfills provided by the framework. Since React Native does not follow a structured release schedule, we support current stable versions and may drop support for older versions in minor releases without considering it a breaking change.

Cloudflare Workers

We support Cloudflare Workers runtime environments. Cloudflare Workers provides native fetch support. Since Cloudflare Workers does not follow a structured release schedule, we support current stable versions and may drop support for older versions in minor releases without considering it a breaking change.

Important Notes

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

Known Build Warnings

UNUSED_EXTERNAL_IMPORT in Vite / Rollup / Nuxt

When bundling your app, you may see warnings like:

"PostgrestError" is imported from external module "@supabase/postgrest-js" but never used in "...supabase-js/dist/index.mjs".
"FunctionRegion", "FunctionsError", "FunctionsFetchError", "FunctionsHttpError" and "FunctionsRelayError" are imported from external module "@supabase/functions-js" but never used in "...".

This is a false positive — your bundle is fine. Here is why it happens:

@supabase/supabase-js re-exports PostgrestError, FunctionsError, and related symbols so you can import them directly from @supabase/supabase-js. However, our build tool merges all imports from the same package into a single import statement in the built output:

// dist/index.mjs (simplified)
import { PostgrestClient, PostgrestError } from '@supabase/postgrest-js'
//       ^ used internally    ^ re-exported for you

Your bundler checks which names from that import are used in the code body, and flags PostgrestError as unused because it only appears in an export statement — not called or assigned. The export itself is the usage, but downstream bundlers don't track this correctly. This is a known Rollup/Vite limitation with re-exported external imports.

Nothing is broken. Tree-shaking and bundle size are unaffected.

To suppress the warning:

Vite / Rollup (vite.config.js or rollup.config.js):

export default {
  build: {
    rollupOptions: {
      onwarn(warning, warn) {
        if (warning.code === 'UNUSED_EXTERNAL_IMPORT' && warning.exporter?.includes('@supabase/'))
          return
        warn(warning)
      },
    },
  },
}

Nuxt (nuxt.config.ts):

export default defineNuxtConfig({
  vite: {
    build: {
      rollupOptions: {
        onwarn(warning, warn) {
          if (warning.code === 'UNUSED_EXTERNAL_IMPORT' && warning.exporter?.includes('@supabase/'))
            return
          warn(warning)
        },
      },
    },
  },
})

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.

Building

# From the monorepo root
pnpm nx build supabase-js

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

Testing

There's a complete guide on how to set up your environment for running locally the supabase-js integration tests. Please refer to TESTING.md.

Badges