JavaScript SDK

Complete reference for the Supabase JavaScript client library

Installation

Install the Supabase JavaScript client library:

npm install @supabase/supabase-js

Initializing

Create a single supabase client for interacting with your database.

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

const supabaseUrl = process.env.SUPABASE_URL
const supabaseKey = process.env.SUPABASE_ANON_KEY
const supabase = createClient(supabaseUrl, supabaseKey)

supabaseUrl · string · required

The unique Supabase URL for your project.

supabaseKey · string · required

The Supabase anon key or service role key for your project.

options · object

Optional configuration parameters.

Show options properties

auth · object

Authentication options.

Show auth properties

autoRefreshToken · boolean · default: "true"

Automatically refresh the token before expiring.

persistSession · boolean · default: "true"

Whether to persist the user session to local storage.

detectSessionInUrl · boolean · default: "true"

Detect OAuth grants in the URL and sign in automatically.

realtime · object

Realtime options.

Show realtime properties

params · object

Custom parameters to pass to the Realtime connection.

global · object

Global configuration options.

Show global properties

headers · object

Custom headers to send with every request.

fetch · function

Custom fetch implementation.

Database Operations

Select Data

Query data from your tables.

const { data, error } = await supabase
  .from('countries')
  .select('*')

data · array

The returned rows from the query.

error · PostgrestError | null

Error object if the query failed, null otherwise.

Select with Filters

const { data, error } = await supabase
  .from('countries')
  .select('name, capital')
  .eq('id', 1)
  .single()

Select with Joins

const { data, error } = await supabase
  .from('countries')
  .select(`
    name,
    cities (
      name,
      population
    )
  `)

Insert Data

Insert rows into your tables.

const { data, error } = await supabase
  .from('countries')
  .insert([
    { name: 'Denmark', code: 'DK' },
    { name: 'Norway', code: 'NO' }
  ])
  .select()

values · object | array · required

The values to insert. Can be a single object or an array of objects.

data · array

The inserted rows (if .select() is used).

error · PostgrestError | null

Error object if the insert failed, null otherwise.

Update Data

Update existing rows in your tables.

const { data, error } = await supabase
  .from('countries')
  .update({ name: 'Australia' })
  .eq('id', 1)
  .select()

values · object · required

The values to update.

Upsert Data

Insert or update rows based on unique constraints.

const { data, error } = await supabase
  .from('countries')
  .upsert({ id: 1, name: 'Australia' })
  .select()

Delete Data

Delete rows from your tables.

const { data, error } = await supabase
  .from('countries')
  .delete()
  .eq('id', 1)

Authentication

Sign Up

Create a new user account.

const { data, error } = await supabase.auth.signUp({
  email: '[e-mail]',
  password: 'example-password',
})

email · string · required

The user’s email address.

password · string · required

The user’s password.

options · object

Optional parameters.

Show options properties

data · object

Additional user metadata.

emailRedirectTo · string

A URL to redirect to after signup.

captchaToken · string

Captcha token for verification.

data · object

Show data properties

user · User | null

The user object.

session · Session | null

The session object.

error · AuthError | null

Error object if signup failed, null otherwise.

Sign In

Sign in an existing user.

const { data, error } = await supabase.auth.signInWithPassword({
  email: '[e-mail]',
  password: 'example-password',
})

Sign Out

Sign out the current user.

const { error } = await supabase.auth.signOut()

Get Session

Get the current session.

const { data: { session } } = await supabase.auth.getSession()

session · Session | null

The current session object or null if no active session.

Get User

Get the current user.

const { data: { user } } = await supabase.auth.getUser()

user · User | null

The current user object or null if not authenticated.

Storage

Upload File

Upload a file to a storage bucket.

const { data, error } = await supabase.storage
  .from('avatars')
  .upload('public/avatar1.png', file, {
    contentType: 'image/png'
  })

path · string · required

The file path including the file name.

fileBody · File | Blob | ArrayBuffer · required

The file data to upload.

options · object

Upload options.

Show options properties

cacheControl · string

Cache control header value.

contentType · string

MIME type of the file.

upsert · boolean · default: "false"

When true, overwrites existing file with the same path.

Download File

Download a file from storage.

const { data, error } = await supabase.storage
  .from('avatars')
  .download('public/avatar1.png')

path · string · required

The file path to download.

data · Blob

The file data as a Blob.

List Files

List all files in a bucket.

const { data, error } = await supabase.storage
  .from('avatars')
  .list('public', {
    limit: 100,
    offset: 0,
    sortBy: { column: 'name', order: 'asc' }
  })

Delete Files

Delete files from storage.

const { data, error } = await supabase.storage
  .from('avatars')
  .remove(['public/avatar1.png', 'public/avatar2.png'])

Get Public URL

Get the public URL for a file.

const { data } = supabase.storage
  .from('avatars')
  .getPublicUrl('public/avatar1.png')

console.log(data.publicUrl)

Realtime

Subscribe to Changes

Listen to database changes in realtime.

const channel = supabase
  .channel('db-changes')
  .on(
    'postgres_changes',
    {
      event: '*',
      schema: 'public',
      table: 'countries'
    },
    (payload) => {
      console.log('Change received!', payload)
    }
  )
  .subscribe()

event · string · required

The database event to listen for: INSERT, UPDATE, DELETE, or * for all.

schema · string · required

The database schema to listen to.

table · string · required

The table to listen to.

filter · string

Optional filter for the change events (e.g., id=eq.1).

Unsubscribe

Stop listening to changes.

await supabase.removeChannel(channel)

Edge Functions

Invoke Function

Invoke a Supabase Edge Function.

const { data, error } = await supabase.functions.invoke('hello-world', {
  body: { name: 'Functions' }
})

functionName · string · required

The name of the Edge Function to invoke.

options · object

Function invocation options.

Show options properties

body · object

The request body to send to the function.

headers · object

Custom headers to send with the request.

method · string · default: "POST"

HTTP method to use.

data · any

The response data from the function.

error · FunctionsError | null

Error object if invocation failed, null otherwise.

TypeScript Support

Generate TypeScript types from your database schema:

import { createClient } from '@supabase/supabase-js'
import { Database } from './types/supabase'

const supabase = createClient<Database>(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
)

// Now all queries are fully typed
const { data } = await supabase
  .from('countries')
  .select('*')
  .eq('id', 1)
  .single()

Error Handling

All methods return an error object if something goes wrong:

const { data, error } = await supabase
  .from('countries')
  .select('*')

if (error) {
  console.error('Error:', error.message)
  return
}

console.log('Data:', data)

Additional Resources

GitHub Repository

View the source code and contribute

NPM Package

View package details and versions