Storage

storage — uploads that earn trust

Stage: Phase 7 — Backend - Reads: design/BRIEF.md, design/SYSTEM.md (§color, §motion for dropzone states) - Writes: components/upload/*, upload route handler or actions, lib/storage.ts, next.config.ts images.remotePatterns

Standard

• Client validation is instant: type and size rejected before a single byte leaves the browser. The server re-validates everything — the client is UX, never security.
• Every upload surface designs all six states: idle, drag-over, uploading with a real percentage, success with preview, error with retry, disabled. A spinner with no percent is not progress.
• Storage keys are server-generated; the user's filename is display metadata, never a path.
• Every stored image renders through next/image with dimensions persisted at upload time — zero CLS from user content.
• Drag-drop is an enhancement over a real <input type="file"> — the keyboard path is the input, always.

Process

1. Read design/BRIEF.md: what gets uploaded, by whom, how big. Pick server-relay vs client-direct and the store (below).
2. Build the authorizing surface first: auth check, zod schema, scoped token/presign or receiving action.
3. Build the dropzone per Upload UX — the input first, drag-drop and progress layered on.
4. Persist the file record with the blob write; wire rendering through next/image + remotePatterns.
5. Verify empirically: upload a valid file, an oversized file, and a wrong-type file renamed to .png — the last two must fail with designed errors on BOTH client and server paths; confirm the rendered image lands with zero CLS.

Choose the path

Two architectures, picked by file size and hosting:

1. Server relay — file posts to a route handler or server action; the server writes to the store. Simplest wiring, but the file transits your function and serverless platforms cap request bodies (Vercel functions ~4.5 MB — verify the current limit before relying on it). Right for avatars and small documents.
2. Client-direct — the browser uploads straight to storage; your server only authenticates and issues a scoped token or presigned URL pinning allowed type, max size, and key prefix. No body cap, no double transfer, real progress. Default for anything beyond tiny files.

Store choice:

• Vercel Blob — the default on this stack: zero infra, public/private access, a built-in client-direct token flow. Exact SDK surface (put/upload/token handler) — verify against current docs first.
• S3-compatible (AWS S3, Cloudflare R2) — when hosting off Vercel, files run large, or egress cost matters; presigned-PUT URLs give the same client-direct shape.
• Either way: the authorizing endpoint checks auth BEFORE issuing anything, and the token constrains content type, size, and prefix — an unscoped upload token is an open bucket.

Upload UX

• Dropzone = styled <label> around the real input (sr-only, not display:none — it must stay focusable); focus-visible ring from the token palette via focus-within; drag-over shifts border to accent and background one neutral step in 150–250ms — no scale jumps, no bounce.
• Real progress requires XMLHttpRequest — xhr.upload.onprogress gives loaded/total; fetch cannot report upload progress. Render a determinate bar + percent text; mirror to aria-live="polite" at coarse steps (25/50/75/done), not every tick.
• Validate before the network: extension AND MIME allowlist, size cap with an honest message ("Max 4 MB — this file is 12.8 MB"), image preview via URL.createObjectURL (revoke it after).
• Multiple files: one row per file with independent progress, error, retry, and remove — one bad file never fails the batch.
• Errors land beside the dropzone, tied via aria-describedby; retry keeps the file selected.

Server validation — zod v4

// the token-issuing handler (client-direct) or the receiving action (server relay)
import { z } from 'zod'

const uploadMeta = z.object({
  type: z.enum(['image/jpeg', 'image/png', 'image/webp'], { error: 'JPEG, PNG, or WebP only' }),
  size: z.number().int().positive().max(4 * 1024 * 1024, { error: 'Max 4 MB' }),
  name: z.string().max(200),   // display only — never a storage path
})

• Key shape: ${prefix}/${crypto.randomUUID()}.${extFromValidatedMime} — extension derived from the validated MIME, never from name (path traversal, collisions).
• Re-serving user files publicly: sniff magic bytes rather than trusting the declared content-type — a renamed .html "image" served inline is stored XSS.
• Persist the record alongside the blob write (per database): url, width, height, alt, size, owner. Read image dimensions server-side at write time so rendering never guesses.
• Content images require alt text at upload; decorative ones store alt: '' explicitly.

After upload — next/image

// next.config.ts
images: { remotePatterns: [{ protocol: 'https', hostname: '<your-store-host>' }] }

• Render with stored dimensions: <Image src={url} width={width} height={height} alt={alt} sizes="(min-width: 768px) 33vw, 100vw" /> — or fill + sizes inside a sized container.
• LCP-critical uploaded images (cover, profile hero) get preload — priority is deprecated in Next 16.
• placeholder="blur" on remote images needs a stored blurDataURL — generate the tiny base64 at upload time or omit the prop; a plain token-colored background beats a broken blur.
• Optimistic preview: show the local object URL immediately while uploading, swap to the stored URL on success, snap back with a visible error on failure — never silently.

Anti-patterns

• accept="image/*" as the only validation — it filters the picker dialog, nothing else.
• put(file.name or any storage key built from the user's filename — greppable; traversal and collisions.
• setInterval driving a progress bar — fake progress; wire xhr.upload.onprogress or show indeterminate honestly.
• <img src= for stored images — bypasses the next/image pipeline: no sizing, no format negotiation, CLS.
• priority on next/image — deprecated in 16; use preload.
• Size cap only on the client — the server schema is the real cap.
• fs.writeFile into public/ at runtime — serverless filesystems are ephemeral; files vanish on the next deploy.
• An onClick dropzone div with no <input type="file"> — keyboard and screen-reader users locked out.
• Submit with no pending state — double submits create orphaned blobs.

Worked example — Loop & Thread, customer review photos as social proof

Moved to references/example.md — read only when this build's case is genuinely ambiguous; the sections above are the decision material.

Composes with

Moved to references/composes.md — the handoff map; load it when orchestrating this skill against its neighbors.