markdown-body entry-content container-lg" itemprop="text">

@netlify/blobs

A JavaScript client for the Netlify Blob Store.

Installation

You can install @netlify/blobs via npm:

npm install @netlify/blobs

Usage

To use the blob store, import the module and create an instance of the Blobs class. The constructor accepts an object with the following properties:

Property	Description	Required
`authentication`	An object containing authentication credentials (see Authentication)	Yes
`siteID`	The Netlify site ID	Yes
`context`	The deploy context to use (defaults to `production`)	No
`fetcher`	An implementation of a fetch-compatible module for making HTTP requests (defaults to `globalThis.fetch`)	No

Example

import assert from 'node:assert'
import { Blobs } from '@netlify/blobs'

const store = new Blobs({
  authentication: {
    token: 'YOUR_NETLIFY_AUTH_TOKEN',
  },
  siteID: 'YOUR_NETLIFY_SITE_ID',
})

await store.set('some-key', 'Hello!')

const item = await store.get('some-key')

assert.strictEqual(item, 'Hello!')

Authentication

Authentication with the blob storage is done in one of two ways:

Using a Netlify API token

import { Blobs } from '@netlify/blobs'

const store = new Blobs({
  authentication: {
    token: 'YOUR_NETLIFY_API_TOKEN',
  },
  siteID: 'YOUR_NETLIFY_SITE_ID',
})

Using a context object injected in Netlify Functions

import { Blobs } from '@netlify/blobs'
import type { Handler, HandlerEvent, HandlerContext } from '@netlify/functions'

export const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
  const store = new Blobs({
    authentication: {
      contextURL: context.blobs.url,
      token: context.blobs.token,
    },
    siteID: 'YOUR_NETLIFY_SITE_ID',
  })
}

API

`get(key: string, { type: string }): Promise<any>`

Retrieves an object with the given key.

Depending on the most convenient format for you to access the value, you may choose to supply a type property as a second parameter, with one of the following values:

arrayBuffer: Returns the entry as an ArrayBuffer
blob: Returns the entry as a Blob
json: Parses the entry as JSON and returns the resulting object
stream: Returns the entry as a ReadableStream
text (default): Returns the entry as a string of plain text

If an object with the given key is not found, null is returned.

const entry = await blobs.get('some-key', { type: 'json' })

console.log(entry)

`set(key: string, value: ArrayBuffer | Blob | ReadableStream | string): Promise<void>`

Creates an object with the given key and value.

If an entry with the given key already exists, its value is overwritten.

await blobs.set('some-key', 'This is a string value')

`setJSON(key: string, value: any): Promise<void>`

Convenience method for creating a JSON-serialized object with the given key.

If an entry with the given key already exists, its value is overwritten.

await blobs.setJSON('some-key', {
  foo: 'bar',
})

`delete(key: string): Promise<void>`

Deletes an object with the given key, if one exists.

await blobs.delete('my-key')

Contributing

Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request on the GitHub repository.

License

Netlify Blobs is open-source software licensed under the MIT license.