Storage

On This Page

How An Upload Flows

Every image upload is three round-trips:

1. Presign. The client asks the API for a short-lived PUT URL and a temporaryKey under tmp/images/.
2. PUT. The browser uploads bytes straight to the bucket. They never pass through your Next.js server.
3. Finalize. The server reads the temp object, validates and re-encodes it with sharp, writes the final key under images/, and deletes the temp.

That split keeps large bodies off the serverless request (no Vercel 4.5 MB body limit) while the server still decides what becomes permanent. Presigned URLs expire in 6 minutes.

Re-encoding through sharp is the security boundary. If sharp cannot decode the file as an image, finalize fails and the temp key is deleted. Original bytes never become the served file.

Package Layout

packages/storage owns key conventions, policy, the sharp pipeline, and the presign/finalize workflow. presignImageUpload and finalizeImageUpload are plain functions that throw StorageError.

packages/api/src/router/storage.ts is a thin adapter: auth, abuse policy, bucket from env, then map StorageError to ORPCError. Storage owns the workflow; API owns the transport.

Configuring Storage

Provider env blocks (AWS S3, Cloudflare R2, MinIO) and a verification step live on Setup: Storage. Same SDK and code path for every S3-compatible store. Only the endpoint and credentials change.

Full per-variable reference: Environment Variables: Object Storage (S3).

File Constraints And Server-Side Validation

The client rejects wrong size or MIME before presign. Server-side sharp is the source of truth: a file that does not decode, or exceeds the dimension limit, fails finalize and the temp object is removed. Final outputs are always re-encoded.

Presigned PUT URLs do not reliably enforce Content-Length across providers, so size is checked three times:

1. Client and presign Zod schema reject anything above MAX_FILE_SIZE before a URL is signed.
2. Finalize runs HeadObject and refuses a temp key whose Content-Length is missing or over the limit. No body download yet.
3. GetObject is read with a hard byte cap. If the stream exceeds the cap (misstated size, or a rewrite between HEAD and GET), the read aborts and the temp key is deleted. The worker never holds more than MAX_FILE_SIZE in memory.

What Gets Uploaded

Required Bucket Configuration

The kit does not provision your bucket. Two settings are easy to miss because they are operational, not code.

CORS. The browser PUTs directly to a presigned URL. Without CORS allowing PUT from your app origin, uploads fail with an opaque toast. Recommended rule:

[
  {
    "AllowedOrigins": ["https://your-app.com"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"]
  }
]

Lifecycle rule for tmp/. The kit deletes temp objects when finalize succeeds, when image processing fails, or when the final PUT fails. It cannot catch a user who abandons the upload after presign: the server is never called again. Expire tmp/ after 1 day as a safety net:

{
  "Rules": [
    {
      "ID": "expire-tmp-uploads",
      "Status": "Enabled",
      "Filter": { "Prefix": "tmp/" },
      "Expiration": { "Days": 1 }
    }
  ]
}

Graceful Degradation

When the storage env block is missing, isStorageEnabled returns false:

• Personal settings and organization settings replace the avatar form with a placeholder that says storage is not configured.
• The AI chat composer hides the image-attachment button. Chat otherwise keeps working.

pnpm setup:doctor reports storage status with every other capability. See Environment Variables for the full env matrix.

Cleanup Behavior

Four helpers cover cleanup from a single key to everything a principal uploaded. The notes below are the gotchas that usually trip people up.

Adding A New Upload Surface

Same pattern for any new file-upload feature.

Where To Go Next

Also useful: Authentication, AI, Database, and Environment Variables.