🍙 @vercel/blob

The Vercel Blob JavaScript API client.

Install

npm install @vercel/blob

Usage

import * as vercelBlob from '@vercel/blob';

// usage
async function someMethod() {
  const blob = await vercelBlob.put(
    'profilesv1/user-12345.txt', // pathname for the blob
    'Hello World!', // body
    { access: 'public' }, // mandatory options
  );

  console.log(blob.url);
  // https://public.blob.vercel-storage.com/n1g9m63etib6gkcjqjpspsiwe7ea/profilesv1/user-12345-NoOVGDVcqSPc7VYCUAGnTzLTG2qEM2.txt
}

API

`put(pathname, body, options)`

Upload a blob to the Vercel Blob API, and returns the URL of the blob.

async function put(
  pathname: string,
  body: ReadableStream | String | ArrayBuffer | Blob // All fetch body types are supported: https://developer.mozilla.org/en-US/docs/Web/API/fetch#body
  options: {
    access: 'public', // mandatory, as we will provide private blobs in the future
    contentType?: string, // inferred from pathname
    contentEncoding?: string, // text based files are gzipped by default when possible
    cacheControl?: string, // default to 1 year
    // `token` defaults to process.env.BLOB_STORE_WRITE_TOKEN on Vercel
    // and can be configured when you connect more stores to a project
    // or using Vercel Blob outside of Vercel
    token?: string,
  }): Promise<{url: string}> {}

del(url, options)

Delete a blob by its full URL. Will throw if the blob does not exist.

async function del(
  url: string,
  options?: {
    token?: string;
  },
): Promise<void> {}

head(url, options)

Get the metadata of a blob by its full URL.

async function head(
  url: string,
  options?: {
    token?: string;
  },
): Promise<{
  size: number;
  uploadedAt: Date;
  pathname: string;
  contentType: string;
  contentDisposition: string;
  contentEncoding?: string;
  cacheControl?: string;
}> {}

Examples

Next.js App Router example.

This example shows a form uploading a file to the Vercel Blob API.

// /app/UploadForm.tsx

'use client';

import type { PutBlobResult } from '@vercel/blob';
import { useState } from 'react';

export default function UploadForm() {
  const [blob, setBlob] = useState<PutBlobResult | null>(null);

  return (
    <>
      <form
        action="/api/upload"
        method="POST"
        encType="multipart/form-data"
        onSubmit={async (event) => {
          event.preventDefault();

          const formData = new FormData(event.currentTarget);
          const response = await fetch('/api/upload', {
            method: 'POST',
            body: formData,
          });
          const blob = (await response.json()) as PutBlobResult;
          setBlob(blob);
        }}
      >
        <input type="file" name="file" />
        <button type="submit">Upload</button>
      </form>
      {blob && (
        <div>
          Blob url: <a href={blob.url}>{blob.url}</a>
        </div>
      )}
    </>
  );
}

// /app/api/upload/route.ts

import * as vercelBlob from '@vercel/blob';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const form = await request.formData();
  const file = form.get('file') as File;

  if (!file) {
    return NextResponse.json(
      { message: 'No file to upload.' },
      { status: 400 },
    );
  }

  const blob = await vercelBlob.put(file.name, file, { access: 'public' });

  return NextResponse.json(blob);
}

A note about Vercel file upload limitations

TODO (depends on final limits when releasing, see https://vercel.slack.com/archives/C02K2HCH5V4/p1681893827433249 and https://vercel.slack.com/archives/C050E79S0HZ/p1681848940242149)
TODO Add note about sending requests to Edge Functions directly via CURL or Node.js scripts (if limits are not raised)

Running examples locally

how to run examples locally (.env.local with token)
how to run examples on Vercel (vc deploy)
how to contribute (pnpm dev to rebuild, example uses local module)
for Vercel contributors, link on how to run the API locally (edge-functions readme link, wrangler dev, pnpm dev for module)