Naly Engineering Notes: Vercel Blob as the Immutable Media Layer for Generated Article Assets

Abstract

TL;DRNaly uses Vercel Blob as the publication boundary for generated media: cover images and social images are created by the article pipeline, uploaded as public blobs, and written back to article rows as stable URLs for hero, card, and Open Graph surfaces. The technology matters less as a storage bucket than as a discipline: once an article is published, its visual evidence should be addressable, cacheable, and reproducible.

Thesis: generated article media should be treated like release artifacts. The model may be probabilistic, but the published asset must be stable. Vercel Blob gives Naly a practical object-store interface for that boundary, while Next.js metadata and article rendering turn the stored URL into distribution surfaces.

Where it sits in Naly

Naly's article system runs on a Next.js and React application stack with Drizzle ORM and Neon for relational state. Generated media sits between the editorial generation step and the public article page:

The article pipeline generates a cover image and social image.
The media bytes are uploaded to Vercel Blob using @vercel/blob.
The returned public URLs are written back to article rows.
The article page reads those URLs for the hero image, listing card image, and Open Graph or social preview image.

That placement is deliberately boring. The article database remains the editorial source of truth, while Blob stores the heavier binary artifacts. A crawler, social scraper, feed consumer, or reader does not need to reproduce the image-generation job. It only needs a durable URL.

Technical mechanism

Vercel Blob is object storage for files uploaded at build time or runtime. The official overview lists cover images, videos, screenshots, and other display/download files as natural use cases, which maps directly to Naly's generated article media. Public Blob storage is also the right access mode for this class of asset because anyone with the URL can read it directly, while writes still require an authenticated token.

The critical API shape is the server-side put operation. A Naly-style upload contract should bind five values together:

pathname: a stable namespace such as articles/{articleId}/cover-{hash}.webp or articles/{slug}/og-{hash}.png.
body: the generated image bytes.
access: public for published article media.
contentType: the exact image MIME type.
cacheControlMaxAge: a value compatible with immutable publication behavior.

The SDK returns metadata such as pathname, url, downloadUrl, contentType, and etag. Naly only needs the public URL for rendering, but the extra metadata is useful for reconciliation and audit. A stronger implementation stores the URL plus content hash, dimensions, MIME type, generation prompt hash, model identifier, and upload timestamp. That turns the image row from a pointer into an evidence record.

The immutable design choice is to avoid overwriting paths. Vercel's SDK supports random suffixes and rejects same-path overwrites by default unless overwrite is explicitly allowed. Naly should lean into that default: a revised image gets a new object URL, and the article row is updated to point at the new object. This avoids the hardest cache problem in media publishing: browser and scraper caches keeping the old bytes while the database believes the asset changed.

On the serving side, public Blob URLs can be fetched through Vercel's CDN. Next.js then has two common paths: render the stored URL directly in article UI, and emit it through metadata for Open Graph and Twitter previews. Next.js also supports generated Open Graph routes, but for Naly's generated media the important distinction is persistence. The image should be generated once, stored, then referenced. Request-time image generation is useful for deterministic templates; persisted Blob assets are better for probabilistic visual generation.

What the literature says

The storage literature makes one point repeatedly: stable names and stable content are different things. IPFS formalized a content-addressed model in which links identify content rather than mutable locations. Naly does not need IPFS to publish article art, but the underlying lesson applies: if the bytes matter, the identifier should change when the bytes change.

Later work on decentralized cloud storage with IPFS is a useful warning against over-romanticizing content addressing. Decentralized systems bring availability, discovery, and operational trade-offs. Vercel Blob is a centralized managed object store, so it does not provide independent public verification by itself. Its advantage is operational simplicity: Naly gets durable object storage, public delivery, and SDK integration without running a peer-to-peer storage network.

The generated-media literature adds a second requirement: provenance is not optional. Recent arXiv work on AI-generated image watermarking surveys the difficulty of making generated image identity robust under editing, compression, and adversarial removal. Another 2026 paper proposes perceptual-hash registries for AI-generated image provenance, emphasizing that exact byte identity is too fragile once media is copied and transformed.

For Naly, the practical conclusion is narrower than a global provenance system. Blob URLs and database rows do not prove universal authenticity. They do give Naly a controlled publication ledger: this article used this generated image, uploaded at this time, with this hash and metadata. That is enough to debug publication failures, reproduce editorial decisions, and keep social previews tied to the published record.

Design trade-offs

Immutable URLs beat overwrites for trust, but they require lifecycle management. Old rejected images can become orphaned storage unless the pipeline marks candidates, winners, and superseded assets explicitly.

Public Blob access improves distribution and caching, but it is inappropriate before editorial approval. Draft assets should either stay private, use a separate store, or be uploaded only after the article is approved for publication.

Persisted generated media beats request-time generation for reproducibility. The cost is storage and cleanup. The benefit is that the public article, card, RSS consumer, and social preview all converge on the same visual artifact.

Database pointers keep rendering simple, but the database must not be the only audit layer. If the row stores only imageUrl, a later debugging session cannot distinguish a bad generation, bad upload, bad MIME type, or bad row update. Storing dimensions, content type, hash, and etag makes the object relationship inspectable.

Content-hash pathnames are more deterministic than random suffixes, but random suffixes are easier and already supported by the SDK. A pragmatic Naly pattern is to compute a hash when convenient, use it in the pathname when available, and still keep overwrite disabled.

Failure modes

The first failure mode is a partial publish: upload succeeds, database update fails. The result is an orphaned blob. This is not reader-visible, but it creates cost and audit noise. The fix is a reconciliation job that lists recent Blob objects and compares them with article media rows.

The second failure mode is a broken pointer: the database points at a URL that is unavailable, deleted, private, or has the wrong content type. The publish step should verify the returned URL and metadata before marking the article ready.

The third failure mode is cache skew. If the same pathname is overwritten, Vercel cache propagation and browser caches may disagree with the new database state. Immutable pathnames make this class of bug mostly disappear.

The fourth failure mode is oversized media. Vercel's server-upload documentation calls out the Vercel Function request body limit for server uploads. Generated article covers should be compressed and dimension-bounded before upload; larger media should use client upload or multipart patterns.

The fifth failure mode is preview divergence. Social scrapers often cache Open Graph images aggressively. If Naly changes the image but keeps the same URL, old previews can persist. New bytes should mean a new URL and a metadata refresh path.

The sixth failure mode is provenance debt. A generated image may be visually correct while losing the record of prompt, model, source article, and approval state. Store the media URL with generation metadata, not as an isolated string.

Implementation notes

A minimal Naly implementation should use a two-phase publication contract:

Generate media into memory or temporary external storage.
Validate MIME type, dimensions, file size, and moderation result.
Upload to Vercel Blob with public access and overwrite disabled.
Record the returned URL and metadata on the article row.
Render hero, card, and Open Graph surfaces from the stored URL.
Reconcile unreferenced blobs separately from the request path.

The article row should not be marked fully publishable until text, sources, generated media, and metadata are all present. That gives Naly one coherent readiness gate instead of separate best-effort surfaces.

For Open Graph, prefer stored Blob URLs when the image is semantically tied to a generated article. Use Next.js generated image routes for deterministic templates, fallbacks, or lightweight text-only previews. The difference is whether the image is an artifact that needs to be audited later. Naly's generated covers are artifacts.

Recommended media metadata fields are: public URL, pathname, MIME type, byte size, width, height, content hash, Blob etag, generator name, generation prompt hash, source article ID, approval state, and uploaded timestamp. The URL serves readers; the metadata serves operators.