Selects and configures Vercel storage: Blob, Edge Config, and Marketplace Neon/Upstash/Supabase/Prisma/Mongo/Convex/Turso, including sunset @vercel/postgres and @vercel/kv migrations. Use when choosing or debugging data stores on Vercel. Not for Neon branch types (neon-postgres-branches), Supabase Auth wiring (nextjs-supabase-auth), or Vercel env var CLI (env-vars).
Selects and configures Vercel storage: Blob, Edge Config, and Marketplace Neon/Upstash/Supabase/Prisma/Mongo/Convex/Turso, including sunset @vercel/postgres and @vercel/kv migrations. Use when choosing or debugging data stores on Vercel. Not for Neon branch types (neon-postgres-branches), Supabase Auth wiring (nextjs-supabase-auth), or Vercel env var CLI (env-vars).
You are an expert in Vercel's storage options. Know which products are active, which are sunset, and when to use each.
When to Use
Trigger this skill when the user is:
Choosing a storage provider for a Vercel/Next.js application
Installing or configuring @vercel/blob, @vercel/edge-config, @neondatabase/serverless, @upstash/redis, @supabase/supabase-js, @prisma/client, mongodb, convex, or @libsql/client
Migrating away from the sunset@vercel/postgres or @vercel/kv packages
Debugging Vercel Marketplace integration env var provisioning
Working in lib/blob/**, lib/storage/**, prisma/**, supabase/**, or similar storage code paths
Setting up Drizzle, Prisma, or Neon with lazy initialization to survive next build
Prerequisites
A Vercel project linked locally (vercel link) so vercel env pull works
Vercel CLI installed (npm i -g vercel) for Marketplace provisioning
Node.js 19+ when using @neondatabase/serverless
Windows host is primary — use PowerShell. On Windows, source is unavailable; use dotenv-cli or PowerShell $env: variable injection for scripts that need .env.local
Procedure
1. Choose the Storage Provider
Use the decision matrix to pick the right product before writing any code.
Need
Use
Package
File uploads, media, documents
Vercel Blob
@vercel/blob
Feature flags, A/B config, edge routing rules
Edge Config
@vercel/edge-config
Relational data, SQL queries
Neon Postgres
@neondatabase/serverless
Key-value cache, sessions, rate limiting
Upstash Redis
@upstash/redis
Postgres + auth + realtime + storage
Supabase
@supabase/supabase-js
Type-safe ORM with migrations
Prisma
@prisma/client
Document database, flexible schemas
MongoDB Atlas
mongodb
Reactive backend with real-time sync
Convex
convex
Edge-native SQLite with replicas
Turso
@libsql/client
Full-text search
Neon Postgres (pg_trgm) or Elasticsearch (Marketplace)
varies
Vector embeddings
Neon Postgres (pgvector) or Pinecone (Marketplace)
varies
2. Provision via Marketplace (Preferred Path)
Preferred: Vercel-managed Neon/Upstash/Supabase/etc. through the Vercel Marketplace. This auto-provisions accounts/resources and injects environment variables into the linked Vercel project.
Browse additional options at https://vercel.com/marketplace or the dashboard at https://vercel.com/dashboard/{team}/stores.
After Marketplace provisioning, pull env vars locally:
vercel env pull .env.local --yes
3. Fallback: Manual / Provider CLI Provisioning
Use the fallback path only when Marketplace is unavailable or you must use an existing external account.
Create the resource via the provider's CLI or dashboard (e.g., Neon CLI, Upstash CLI, Supabase dashboard).
Copy the connection string / URL / token into Vercel project env vars (dashboard or vercel env add).
Pull locally: vercel env pull .env.local --yes
Neon CLI fallback note: For Vercel-managed Neon projects, CLI operations require a Neon API key; do not rely on the normal browser-auth login flow alone.
import { put, del, list, get } from'@vercel/blob'// Upload from server (public)const blob = awaitput('images/photo.jpg', file, {
access: 'public',
})
// blob.url → public URL// Upload private fileconst privateBlob = awaitput('docs/secret.pdf', file, {
access: 'private',
})
// Read private file backconst privateFile = awaitget(privateBlob.url) // returns ReadableStream + metadata// Client upload (up to 5 TB)import { upload } from'@vercel/blob/client'const blob = awaitupload('video.mp4', file, {
access: 'public',
handleUploadUrl: '/api/upload', // Your token endpoint
})
// List blobsconst { blobs } = awaitlist()
// Conditional get with ETagsconst response = awaitget('images/photo.jpg', {
ifNoneMatch: previousETag,
})
if (response.statusCode === 304) {
// Not modified, use cached version
}
// Deleteawaitdel('images/photo.jpg')
Private Storage (public beta): Use access: 'private' for files that should not be publicly accessible. Read them back with get(). Do NOT use private access for files that need to be served publicly — it leads to slow delivery and high egress costs.
Blob Data Transfer: Vercel Blob uses two delivery strategies — Fast Data Transfer (94 cities, latency-optimized) and Blob Data Transfer (18 hubs, volume-optimized for large assets). The system automatically routes via the optimal path.
Use when: Media files, user uploads, documents, any large unstructured data.
Vercel Edge Config — Global Configuration
Ultra-low-latency key-value store for application configuration. Not a database — designed for config data that must be read instantly at the edge.
import { get, getAll, has } from'@vercel/edge-config'// Read a single value (< 1ms at the edge)const isFeatureEnabled = awaitget('feature-new-ui')
// Read multiple valuesconst config = awaitgetAll(['feature-new-ui', 'ab-test-variant', 'redirect-rules'])
// Check existenceconst exists = awaithas('maintenance-mode')
Use when: Feature flags, A/B testing config, dynamic routing rules, maintenance mode toggles. Anything that must be read at the edge with near-zero latency.
Do NOT use for: User data, session state, frequently written data. Edge Config is optimized for reads, not writes.
Next.js 16: @vercel/edge-config@^1.4.3 supports cacheComponents and the renamed proxy.ts (formerly middleware.ts).
Neon Postgres (replaces @vercel/postgres)
Serverless Postgres with branching, auto-scaling, and connection pooling. The driver is GA at @neondatabase/serverless@^1.0.2 and requires Node.js 19+.
// Direct Neon usageimport { neon } from'@neondatabase/serverless'const sql = neon(process.env.DATABASE_URL!)
const users = await sql`SELECT * FROM users WHERE id = ${userId}`// With Drizzle ORMimport { drizzle } from'drizzle-orm/neon-http'import { neon } from'@neondatabase/serverless'const sql = neon(process.env.DATABASE_URL!)
const db = drizzle(sql)
Build-time safety — CRITICAL: The neon() call above throws if DATABASE_URL is not set. Since Next.js evaluates top-level module code at build time, this will crash next build when env vars aren't yet configured (e.g., first deploy before Marketplace provisioning). Use lazy initialization:
HARD RULE — Do NOT use JavaScript Proxy wrappers around the DB client. A common pattern is wrapping db in a Proxy for lazy initialization. This breaks libraries like NextAuth/Auth.js that inspect the DB adapter object (e.g., checking method existence, iterating properties). The Proxy intercepts those checks and breaks the auth request chain, causing hangs with no error. Use a plain getDb() function or a simple module-level lazy let instead.
Drizzle Kit migrations: drizzle-kit and tsx do NOT auto-load .env.local. Source env vars manually or use dotenv:
Install via Vercel Marketplace: vercel integration add turso
6. Migrate from Sunset Packages
@vercel/postgres and @vercel/kv are SUNSET. These packages no longer exist as first-party Vercel products. Use the marketplace replacements.
From @vercel/postgres → Neon
- import { sql } from '@vercel/postgres'+ import { neon } from '@neondatabase/serverless'+ const sql = neon(process.env.DATABASE_URL!)
Drop-in replacement: For minimal migration effort, use @neondatabase/vercel-postgres-compat which provides API-compatible wrappers for @vercel/postgres imports.
From @vercel/kv → Upstash Redis
- import { kv } from '@vercel/kv'- await kv.set('key', 'value')- const value = await kv.get('key')+ import { Redis } from '@upstash/redis'+ const redis = Redis.fromEnv()+ await redis.set('key', 'value')+ const value = await redis.get('key')
Pitfalls
next build crashes with missing DATABASE_URL: The neon() call throws at module-eval time. Always use lazy initialization (getDb() pattern) — never call neon() at top-level scope.
Proxy wrappers break NextAuth/Auth.js: Wrapping the DB client in a JS Proxy for lazy init causes auth libraries to hang silently. Use a plain function or let variable instead. This is a HARD RULE.
drizzle-kit / tsx don't read .env.local: Only Next.js auto-loads .env.local. Use dotenv-cli (npx dotenv -e .env.local -- ...) for all standalone Node scripts. On Windows, source is not available — use dotenv-cli exclusively.
Using Blob private access for public files: Leads to slow delivery and high egress costs. Only use access: 'private' for files that should not be publicly accessible.
Edge Config used as a database: Edge Config is optimized for reads, not writes. Do NOT use it for user data, session state, or frequently written data.
Vercel-managed Neon CLI auth: CLI operations on Vercel-managed Neon projects require a Neon API key — the browser-auth login flow alone is insufficient.
Forgetting vercel env pull after Marketplace provisioning: After adding an integration, always run vercel env pull .env.local --yes locally so the new env vars are available for local dev.
Node.js version mismatch: @neondatabase/serverless requires Node.js 19+. Check node -v before installing.
Next.js 16 proxy.ts rename: @vercel/edge-config@^1.4.3 supports the renamed proxy.ts (formerly middleware.ts) and cacheComponents. Ensure you are on ^1.4.3 or later.
Verification
Confirm integration is installed:
vercel integration list
Expected: the storage integration (e.g., neon, upstash) appears in the list.
Confirm env vars were provisioned and pulled:
vercel env pull .env.local --yes
Then inspect .env.local for the expected keys (e.g., DATABASE_URL, UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN, BLOB_READ_WRITE_TOKEN, EDGE_CONFIG). Use YOUR_KEY placeholders when sharing examples — never commit real secrets.
Verify Blob upload works:
import { put } from'@vercel/blob'const blob = awaitput('test.txt', 'hello', { access: 'public' })
console.log(blob.url) // should print a vercel-storage.com URL
Verify Edge Config read:
import { get } from'@vercel/edge-config'const val = awaitget('test-key')
console.log(val)
Verify Neon query (with lazy init):
import { getDb } from'@/db'const db = getDb()
const result = await db.execute('SELECT 1 AS ok')
console.log(result) // [{ ok: 1 }]
