---

name: vercel-blob-asset-persistence description: Use when a feature generates media (images from fal.ai, audio from a TTS gateway) whose provider URLs expire, and the output must persist. Covers Vercel Blob storage, a token-guarded client, dynamic import so the build survives without the package, and durable user-scoped pathnames.

Persisting Generated Assets to Vercel Blob

When to trigger

An AI feature returns a URL that expires (fal.ai image URLs, a gateway TTS clip) and the user must be able to open that asset days later from their gallery.

Provider URLs are ephemeral; copy the bytes

The generation provider hands back a short-lived URL. Fetch those bytes once and re-upload them to your own store so the durable URL you show the user is yours, not the provider's.

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

const res = await put(pathname, bytes, {
  access: "public",
  token: process.env.BLOB_READ_WRITE_TOKEN!,
  contentType: "image/webp",
  addRandomSuffix: true,
});
return res.url; // durable, safe to store on the row

Guard configuration; never assume the token

The store is configured only when BLOB_READ_WRITE_TOKEN is present. Expose an isStorageConfigured() check and throw a clear STORAGE_NOT_CONFIGURED sentinel rather than a raw undefined-token error, so a route can return a clean 503 when storage is not wired.

Keep the build safe when the package is not installed yet

If @vercel/blob may not be a dependency in every environment, load it via a computed dynamic import so the typecheck and build never resolve a missing module:

const specifier = ["@vercel", "blob"].join("/"); // stops tsgo resolving it at typecheck
const mod = await import(/* webpackIgnore: true */ specifier);

Declare a local interface for just the put/del surface you call so the module typechecks without the package's own types.

Organize the namespace

Prefix objects under a dated, user-scoped path (for example dd/images/{yyyy-mm}/{clerkId}/...) so the store is browsable, per-user, and easy to expire or audit by month. Keep the token server-only; never send it to the client.

Pitfalls

• Storing the provider's ephemeral URL on the row means the asset 404s once it expires. Persist your Blob URL, not theirs.
• A top-level import("@vercel/blob") fails the build in an env where the package is absent. Compute the specifier and dynamic-import it.
• Reading BLOB_READ_WRITE_TOKEN at module load can crash a build without the env. Read it at call time behind the configured check.
• Exposing the read-write token to the client hands out write access to your whole store. Keep uploads on the server; use a scoped client token for direct browser uploads if you need them.