vercel-blob

# Vercel Blob (Object Storage)

**Status**: Production Ready
**Last Updated**: 2025-12-14
**Dependencies**: None
**Latest Versions**: `@vercel/blob@2.0.0`

---

## Quick Start (3 Minutes)

### 1. Create & Configure

```bash
# In Vercel dashboard: Storage → Create Database → Blob
vercel env pull .env.local
```

Creates: `BLOB_READ_WRITE_TOKEN`

### 2. Install

```bash
bun add @vercel/blob
```

### 3. Upload File (Server Action)

```typescript
'use server';

import { put } from '@vercel/blob';

export async function uploadFile(formData: FormData) {
  const file = formData.get('file') as File;

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

  return blob.url;
}
```

### 4. Basic Operations

```typescript
import { put, del, list } from '@vercel/blob';

// Upload
const blob = await put('path/file.jpg', file, { access: 'public' });

// Delete
await del(blob.url);

// List with pagination
const { blobs, cursor } = await list({ prefix: 'uploads/', limit: 100 });
```

---

## Critical Rules

### Always Do

| Rule | Why |
|------|-----|
| Use client upload tokens for client-side uploads | Never expose `BLOB_READ_WRITE_TOKEN` to client |
| Set `contentType` explicitly | Correct browser handling for PDFs, videos |
| Use `access: 'public'` for CDN caching | Private files bypass CDN |
| Validate file type and size before upload | Prevent invalid uploads |
| Use pathname organization | `avatars/`, `uploads/`, `documents/` |
| Delete old files when replacing | Manage storage costs |

### Never Do

| Rule | Why |
|------|-----|
| Expose `BLOB_READ_WRITE_TOKEN` to client | Security vulnerability |
| Upload files >500MB without multipart | Use `createMultipartUpload` API |
| Use generic filenames | Use `${Date.now()}-${name}` or `addRandomSuffix: true` |
| Skip file validation | Always validate type/size |
| Store sensitive data unencrypted | Encrypt before upload |
| Forget to handle pagination | `list()` returns max 1000 files |