Skip to content
Last updated on June 7, 2023
13 min read

@vercel/blob

Learn how to use the Vercel Blob SDK to access your blob store from your apps in Edge Functions.

Note: Vercel Blob is currently in private beta. Sign up for the waitlist now

Sign up

To start using Vercel Blob SDK, follow the steps in our Blob quickstart docs.

A read-write token is required to interact with the Blob SDK. When you create a Blob store in your Vercel Dashboard, an Environment Variable with the value of the token is created for you. You have the following options when deploying your application:

  • If you deploy your application in the same Vercel project where your Blob store is located, you do not need to specify the token parameter, as it's default value is equal to the store's token Environment Variable
  • If you deploy your application in a different Vercel project or scope, you can create an Environment Variable there and assign the token value from your Blob store settings to this variable. You will then set the token parameter to this Environment Variable
  • If you deploy your application outside of Vercel, you can copy the token value from the store settings and pass it as the token parameter when you call a Blob SDK method

To use the methods of the Blob SDK, you will need to call them inside an Edge Function or a Serverless Function. You can then call the function from the front-end of your application. In the examples below, we will be using Edge Functions.

This example creates an Edge Function that accepts a file from a multipart/form-data form and uploads it to the Blob store. The function returns a unique URL for the blob.

pages/api/upload.ts
import { put } from '@vercel/blob';
import { NextResponse } from 'next/server';
 
export const config = {
  runtime: 'edge',
};
 
export default async function upload(request) {
  const form = await request.formData();
  const file = form.get('file') as File;
  const blob = await put(file.name, file, { access: 'public' });
 
  return NextResponse.json(blob);
}

The put method uploads a blob object to the Blob store.

put(pathname, body, options);

It accepts the following parameters:

  • pathname: (Required) A string specifying the base value of the return URL
  • body: (Required) A blob object as ReadableStream, String, ArrayBuffer or Blob based on these supported body types
  • options: (Required) A JSON object with the following required and optional parameters:
Parameter
Required
Values
access
Yes
public - Support for private is planned
contentType
No
A string indicating the media type. By default, it's extracted from the pathname's extension.
token
No
A string specifying the read-write token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel as explained in Read-write token

put() returns a JSON object with the following data for the created blob object:

{
  size: `number`;
  uploadedAt: `Date`;
  pathname: `string`;
  contentType: `string`;
  contentDisposition: `string`;
  url: `string`;
}

An example url is:

url: "https://public.blob.vercel-storage.com/n1g9m63etib6gkcjqjpspsiwe7ea/profilesv1/user-12345-NoOVGDVcqSPc7VYCUAGnTzLTG2qEM2.txt"

This example creates an Edge Function that deletes a blob object from the Blob store.

pages/api/blob.ts
import { del } from '@vercel/blob';
 
export const config = {
  runtime: 'edge',
};
 
export default async function delete(request: Request) {
  const { searchParams } = new URL(request.url);
  const urlToDelete = searchParams.get('url');
  const { url } = await del(urlToDelete);
 
  return new Response(url);
};

The del method deletes a blob object from the Blob store.

del(url, options);

It accepts the following parameters:

  • url: (Required) A string or Array of strings specifying the unique URL(s) of the blob object(s) to delete
  • options: (Optional) A JSON object with the following optional parameter:
Parameter
Required
Values
token
No
A string specifying the read-write token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel as explained in Read-write token

del() returns one of the following:

  • a JSON object with the deleted blob object's metadata
  • a JSON object with an array of deleted blob objects metadata
  • null if the blob object(s) was not found
{
  size: `number`;
  uploadedAt: `Date`;
  pathname: `string`;
  contentType: `string`;
  contentDisposition: `string`;
  url: `string`;
}

del() returns any response if successful. If it fails, it will throw an error such as if the blob object url does not exist.

This example creates an Edge Function that returns a blob object's metadata.

/pages/api/blob.ts
import { head } from '@vercel/blob';
import { NextResponse } from 'next/server';
 
export const config = {
  runtime: 'edge',
};
 
export default async function blob(request: Request) {
  const { searchParams } = new URL(request.url);
  const blobUrl = searchParams.get('url');
  const blobDetails = await head(blobUrl);
 
  return NextRequest.json(blobDetails);
}

The head method returns a blob object's metadata.

head(url, options);

It accepts the following parameters:

  • url: (Required) A string specifying the unique URL of the blob object to read
  • options: (Optional) A JSON object with the following optional parameter:
Parameter
Required
Values
token
No
A string specifying the read-write token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel as explained in Read-write token

head() returns one of the following:

  • a JSON object with the requested blob object's metadata
  • null if the blob object was not found
{
  size: `number`;
  uploadedAt: `Date`;
  pathname: `string`;
  contentType: `string`;
  contentDisposition: `string`;
  url: `string`;
}

This example creates an Edge Function that returns a list of blob objects in a Blob store.

pages/api/blob.ts
import { list } from '@vercel/blob';
import { NextResponse } from 'next/server';
 
export const config = {
  runtime: 'edge',
};
 
export default async function blobs(request: Request) {
  const { blobs } = await list();
  return NextResponse.json(blobs);
}

The list method returns a list of blob objects in a Blob store.

list(options);

It accepts the following parameters:

  • options: (Optional) A JSON object with the following optional parameters:
Parameter
Required
Values
token
No
A string specifying the read-write token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel as explained in Read-write token
limit
No
A number specifying the maximum number of blob objects to return. It defaults to 1000
prefix
No
A string used to filter for blob objects contained in a specific folder assuming that the folder name was used in the pathname when the blob object was uploaded
cursor
No
A string obtained from a previous response for pagination of retults

list() returns a JSON object in the following format:

blobs: {
  size: `number`;
  uploadedAt: `Date`;
  pathname: `string`;
  contentType: `string`;
  contentDisposition: `string`;
  url: `string`;
}[]
cursor?: `string`;
hasMore: `boolean`;

For a long list of blob objects (the default list limit is 1000), you can use the cursor and hasMore parameters to paginate through the results as shown in the example below:

let hasMore = true;
let cursor;
 
while (hasMore) {
  const listResult = await vercelBlob.list({
    cursor,
  });
  hasMore = listResult.hasMore;
  cursor = listResult.cursor;
}

When you make a request to the SDK using any of the above methods, they will return an error if the request fails due to any of the following reasons:

  • Missing required parameters
  • An invalid token or a token that does have access to the Blob object
  • Unforeseen or unknown errors

To catch these errors, wrap your requests with a try/catch statement as shown below:

import * as vercelBlob from '@vercel/blob';
 
try {
  await vercelBlob.put(...);
} catch (error) {
  if (error instanceof vercelBlob.BlobAccessError) {
    // handle a recognized error
  } else {
    // throw the error again if it's unknown
    throw error;
  }
}