How it works

Every blob is a { meta, ...content } envelope. Whatever writes it decides the content keys; meta carries the facts about the entry, so a template can destructure both together.

Reads & writes never throw. A failed read resolves to { meta: { error } } & a failed write to { statusCode, body }, so a template renders a fallback instead of failing the build.

readBlob resolves in this order:

1. The local cache, when the entry exists & is younger than ttl.
2. Netlify Blobs otherwise, & the result is written into the cache for the next build.
3. The stale cache, if the store could not be reached & staleIfError is on. The envelope comes back with meta.stale & meta.cacheAge added, & the original meta.generatedAt intact.

writeBlob writes to the store & refreshes the cached copy, so a read that follows it sees the new value immediately.

cacheDir holds a mirror of the store at <cacheDir>/<storeName>/<name>.json. Each file wraps the value with the time it was fetched:

{
	"cachedAt": "2026-09-05T06:15:00.000Z",
	"value": { "meta": { "generatedAt": "2026-09-05T06:00:00.000Z" }, "entries": [] }
}

It is a cache, not a fixture: written by the plugin, never committed, & safe to delete. Add it to .gitignore:

.netlify

Warming it takes one build with credentials present. Every build after that runs offline until the TTL lapses. The cache applies to every build, not just local development: caching is governed by ttl, never by NODE_ENV.

NETLIFY_SITE_ID & NETLIFY_TOKEN must be set for any read or write that reaches Netlify Blobs through the default @netlify/blobs factory. Missing credentials are a configuration error: the failure is logged, & the read or write converts it into the usual envelope or { statusCode: 500 }, so the build still completes.

A custom getStore factory skips the check, because it owns its own configuration.