🚨 This repository has been moved and will be archived on October 10, 2025

All development has moved to the Supabase JS Monorepo

If you're looking for the README of storage-js, you can find it at:
https://github.com/supabase/supabase-js/tree/master/packages/core/storage-js

What happened?

This repository was merged into the main Supabase JS monorepo for better coordination, testing, and releases.

What you need to do:

• 📖 For documentation: Visit the new storage-js location
• 🐛 For issues: Create them in the supabase-js repository
• 🔧 For contributions: See the Contributing Guide
• 📚 For migration help: Read the Migration Guide

If you have open work:

• Uncommitted changes: Manually transport your work to the monorepo (file structure is the same under packages/core/storage-js/)
• Open PRs: Tag a maintainer in your PR and we'll help you migrate it
• Issues: Will be transported to the supabase-js repository

⚠️ This is the old repository. Please use the supabase-js monorepo going forward.

JS Client library to interact with Supabase Storage.

• Documentation: https://supabase.io/docs/reference/javascript/storage-createbucket

npm install @supabase/storage-js

import{StorageClient}from'@supabase/storage-js'constSTORAGE_URL='https://<project_ref>.supabase.co/storage/v1'constSERVICE_KEY='<service_role>'//! service key, not anon keyconststorageClient=newStorageClient(STORAGE_URL,{apikey: SERVICE_KEY,Authorization: `Bearer ${SERVICE_KEY}`,})

• Create a new Storage bucket:

  const{ data, error }=awaitstorageClient.createBucket('test_bucket',// Bucket name (must be unique){public: false}// Bucket options)

• Retrieve the details of an existing Storage bucket:

  const{ data, error }=awaitstorageClient.getBucket('test_bucket')

• Update a new Storage bucket:

  const{ data, error }=awaitstorageClient.updateBucket('test_bucket',// Bucket name{public: false}// Bucket options)

• Remove all objects inside a single bucket:

  const{ data, error }=awaitstorageClient.emptyBucket('test_bucket')

• Delete an existing bucket (a bucket can't be deleted with existing objects inside it):

  const{ data, error }=awaitstorageClient.deleteBucket('test_bucket')

• Retrieve the details of all Storage buckets within an existing project:

  const{ data, error }=awaitstorageClient.listBuckets()

• Upload a file to an existing bucket:

  constfileBody= ... // load your file hereconst{ data, error }=awaitstorageClient.from('bucket').upload('path/to/file',fileBody)

  Note:
  The path in data.Key is prefixed by the bucket ID and is not the value which should be passed to the download method in order to fetch the file.
  To fetch the file via the download method, use data.path and data.bucketId as follows:

  const{ data, error }=awaitstorageClient.from('bucket').upload('/folder/file.txt',fileBody)// check for errorsconst{ data2, error2 }=awaitstorageClient.from(data.bucketId).download(data.path)

  Note: The upload method also accepts a map of optional parameters. For a complete list see the Supabase API reference.

• Download a file from an exisiting bucket:

  const{ data, error }=awaitstorageClient.from('bucket').download('path/to/file')

• List all the files within a bucket:

  const{ data, error }=awaitstorageClient.from('bucket').list('folder')

  Note: The list method also accepts a map of optional parameters. For a complete list see the Supabase API reference.

• Replace an existing file at the specified path with a new one:

  constfileBody= ... // load your file hereconst{ data, error }=awaitstorageClient.from('bucket').update('path/to/file',fileBody)

  Note: The upload method also accepts a map of optional parameters. For a complete list see the Supabase API reference.

• Move an existing file:

  const{ data, error }=awaitstorageClient.from('bucket').move('old/path/to/file','new/path/to/file')

• Delete files within the same bucket:

  const{ data, error }=awaitstorageClient.from('bucket').remove(['path/to/file'])

• Create signed URL to download file without requiring permissions:

  constexpireIn=60const{ data, error }=awaitstorageClient.from('bucket').createSignedUrl('path/to/file',expireIn)

• Retrieve URLs for assets in public buckets:

  const{ data, error }=awaitstorageClient.from('public-bucket').getPublicUrl('path/to/file')

Supplying .throwOnError() will throw errors instead of returning them as a property on the response object.

try{const{ data }=awaitstorageClient.from('bucket').throwOnError().download('path/to/file')}catch(error){console.error(error)}

We are building the features of Firebase using enterprise-grade, open source products. We support existing communities wherever possible, and if the products don’t exist we build them and open source them ourselves. Thanks to these sponsors who are making the OSS ecosystem better for everyone.