@vercel/blob

🍙 @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?: '...';
}> {}

Examples

• Next.js App Router examples
• https.get, axios, got, and CURL

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);

  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)