@vercel/blob

# @vercel/blob

Object storage for Vercel apps: upload a file, get a public URL.

## Install

```bash
npm install @vercel/blob
```

## Credentials

1. Vercel dashboard -> Storage -> Create -> Blob -> connect to your project.
2. This sets `BLOB_READ_WRITE_TOKEN`. Locally: `vercel env pull .env.local`.
3. Without the token every call throws `No read-write token found`.

## Which method

| Need | Use |
|---|---|
| Browser uploads, any size (default) | `upload()` from `@vercel/blob/client` + `handleUpload()` in a route |
| Small files (<4.5 MB) from your server | `put()` |
| List / delete / metadata | `list()`, `del()`, `head()` |

Server functions on Vercel have a 4.5 MB request body limit. Do not send large files through your own route; use client uploads.

## Next.js App Router: client upload

`app/api/upload/route.ts`

```ts
import { handleUpload, type HandleUploadBody } from '@vercel/blob/client';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const body = (await request.json()) as HandleUploadBody;
  try {
    const json = await handleUpload({
      body,
      request,
      onBeforeGenerateToken: async () => {
        // Authenticate the user here and throw if not allowed.
        return {
          allowedContentTypes: ['application/pdf', 'image/*'],
          maximumSizeInBytes: 20 * 1024 * 1024,
          addRandomSuffix: true,
        };
      },
      onUploadCompleted: async ({ blob }) => {
        // Save blob.url to your DB. Not called on localhost without a tunnel.
      },
    });
    return NextResponse.json(json);
  } catch (e) {
    return NextResponse.json({ error: (e as Error).message }, { status: 400 });
  }
}
```

`app/upload-form.tsx`

```tsx
'use client';
import { upload } from '@vercel/blob/client';

export function UploadForm() {
  async function onChange(e: React.ChangeEvent<HTMLInputElement>) {
    const file = e.target.files?.[0];
    if (!file) return;
    const blob = await upload(file.name, file, {
      access: 'public',
      handleUploadUrl: '/api/upload',
    });
    console.log(blob.url);
  }
  return <input type="file" onChange={onChange} />;
}
```

Blobs are public by URL. Do not store private documents without access controls.

## Docs

- https://vercel.com/docs/vercel-blob/client-upload
- https://vercel.com/docs/storage/vercel-blob

# @vercel/blob: agent rules

## Install
`npm install @vercel/blob` (use the project's package manager; do not switch it)

## Env
- `BLOB_READ_WRITE_TOKEN`: created when a Blob store is connected. Vercel dashboard -> Storage -> Create -> Blob -> connect to project.
- Local: `vercel env pull .env.local`. Never hardcode or commit the token.
- If the token is absent: finish the code, then tell the user the exact steps above. Do not invent a token.

## Next.js App Router: the one path
1. `app/api/upload/route.ts`: `POST` calling `handleUpload({ body, request, onBeforeGenerateToken, onUploadCompleted })` from `@vercel/blob/client`.
2. Client component: `upload(file.name, file, { access: 'public', handleUploadUrl: '/api/upload' })` from `@vercel/blob/client`.
3. Set `allowedContentTypes` and `maximumSizeInBytes` in `onBeforeGenerateToken`.
4. Persist `blob.url` in your DB or state; Blob does not give you a per-user index.

## Mistakes agents make
1. Posting the file through your own route with `put()`. Vercel functions cap request bodies at 4.5 MB; use client upload for anything larger (PDFs up to 20 MB included).
2. Leaving `onBeforeGenerateToken` without auth. Anyone can mint upload tokens. Check the session there and throw if unauthorized.
3. Expecting `onUploadCompleted` on localhost. It is called by Vercel, so it only fires on a deployed URL or a tunnel. Save the URL client-side after `upload()` resolves.
4. Treating blobs as private. `access: 'public'` URLs are readable by anyone with the link.
5. Adding UI or icon libraries that were not requested.

## Verify
- `npm run build` and `npx tsc --noEmit` pass.
- Without a token: `curl -s -X POST localhost:3000/api/upload -H 'content-type: application/json' -d '{}'` returns an error naming the missing token or body.
- With a token: upload a small file in the browser; the returned `blob.url` opens in a new tab.

## Docs
https://vercel.com/docs/vercel-blob/client-upload

# Vercel Blob

> Object storage for web apps. `@vercel/blob` uploads files from a server or directly from the browser and returns a URL. Requires a Blob store connected to a Vercel project, which sets `BLOB_READ_WRITE_TOKEN`.

Default for Next.js: client uploads with `handleUpload()` in a route handler and `upload()` from `@vercel/blob/client`. Do not proxy large files through a server function (4.5 MB request limit).

## Start here

- [Client uploads](https://vercel.com/docs/vercel-blob/client-upload.md): Browser-to-Blob uploads for any file size, token route, content-type and size limits, multipart.
- [Vercel Blob overview](https://vercel.com/docs/storage/vercel-blob.md): Concepts, store setup, pricing, limits.

## Package

- [@vercel/blob on npm](https://www.npmjs.com/package/@vercel/blob): Install and README.
- [Source](https://github.com/vercel/storage/tree/main/packages/blob): Repo, AGENTS.md, issues.

## Setup facts

- Create store: Vercel dashboard -> Storage -> Create -> Blob -> connect to project.
- Local token: `vercel env pull .env.local`.
- Uploaded blobs are readable by URL.

## Optional

- [Vercel llms.txt](https://vercel.com/llms.txt): Platform index.