OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add netlify/context-and-tools --skill netlify-blobs
Store and retrieve unstructured objects, file uploads, and cache-like state on Netlify using the @netlify/blobs key/value API from Functions, Edge Functions, and Build Plugins. Use when a task involves saving user file or image uploads, persisting form or contact-form submissions, storing generated output from Background Functions (sitemaps/processed media/bulk-email results), building read-only asset stores, adding client-side blob expiration, or wiring file-based blob uploads at deploy time. Not for per-user, transactional, or relational data (counters/balances/sessions) — reach for Netlify DB there instead.
npx skills add netlify/context-and-tools --skill netlify-blobs
Modern import — reach for this:
Install: npm install @netlify/blobs. Fetch API is required (built into Node 18+); otherwise pass a custom fetch.
Two ways to open a store — use the options-object form when you need consistency or a custom fetch (the string form cannot pass them):
siteID, token, deployID, and region are set automatically inside Functions, Edge Functions, and Build Plugins — do not pass them manually there.
getStore(name) — site-scoped. Persists across deploys and is shared across ALL deploy contexts. Code on a Deploy Preview reads, overwrites, and deletes production data. Never seed throwaway data or run destructive tests from a preview.getDeployStore(name) — scoped to one deploy; isolated from production. Use this for throwaway/per-deploy data, or use a context-specific store name for isolation.Blobs have no built-in access control — the serving function is the gate. Default to private: gate reads behind an authenticated function rather than exposing blobs publicly. Never accept an arbitrary caller-supplied key against a store holding sensitive data.
set)Edge Function form is identical but imports Context from @netlify/edge-functions.
setJSON)get) — always null-checkPass type for other formats: get(key, { type: "json" | "arrayBuffer" | "blob" | "stream" | "text" }).
Write only if the key is new:
Write only if the entry matches a known ETag (compare-and-swap):
Do not build counters, balances, or read-modify-write logic on a blob key — even with onlyIfMatch retries. That is transactional data; use Netlify DB.
Manual pagination (returns an AsyncIterator):
Hierarchical listing — group keys with /, set directories: true to list one level, and use a trailing slash on prefix to drill in (without it, cats would also match catsuit):
Build plugins can READ from any of the site's stores, but can WRITE only to deploy-specific stores (getDeployStore).
Blobs have no TTL. Store a timestamp in metadata, check it on read, and delete when expired:
getWithMetadata)getWithMetadata returns { data, etag, metadata }, or null if the key is absent. getMetadata(key) returns { metadata, etag } (no blob body) — use it to check existence cheaply.
Store instance methods:
set(key, value, { metadata, onlyIfMatch, onlyIfNew }) → { modified, etag }. value is ArrayBuffer | Blob | string.setJSON(key, value, { metadata, onlyIfMatch, onlyIfNew }) → { modified, etag }.get(key, { consistency, type }) → blob in requested format, or null.getWithMetadata(key, { consistency, etag, type }) → { data, etag, metadata } or null.getMetadata(key, { consistency, etag }) → { metadata, etag } or null.list({ directories, paginate, prefix }) → { blobs, directories } (auto-paginates unless paginate: true).delete(key) → undefined.deleteAll() → { deletedBlobs }.Module functions:
listStores({ paginate }) → { stores }. Excludes deploy-specific stores.Default is eventual: writes are globally readable immediately; updates and deletes propagate within 60 seconds. Opt into strong consistency per store or per read:
The CLI always uses strong consistency.
Deploy-specific stores default to the function's region. Override with region:
Available regions: https://docs.netlify.com/build/functions/configuration#region
Place blob files under .netlify/blobs/deploy/ in the site's base directory; Netlify uploads them to deploy-specific stores (preserving directory structure) after build, before deploy.
$: $mouse.jpg.json for mouse.jpg, dogs/$good-boy.jpg.json for dogs/good-boy.jpg..netlify/blobs/deploy is wiped before each build — files must be created DURING the build (build command or plugin). Files committed to the repo beforehand are NOT uploaded./, no :, max 64 bytes./, max 600 bytes, any Unicode. (UTF-8: most chars 1 byte, some more, e.g. à = 2 bytes.)list and listStores cap pages at 1,000 entries/stores.onlyIfMatch / onlyIfNew.Surface the error and read the function logs. Do not invent REST endpoints or side-channel APIs to retry a failed store operation.
Inspect blobs with netlify blobs:list / :get / :set / :delete — reference: https://cli.netlify.com/commands/blobs/
If you wrote to site-wide stores with @netlify/blobs ≤ 6.5.0, data becomes inaccessible after upgrading (namespacing change). Migrate with the latest CLI, which makes the store accessible on 7.0.0+:
These are org conventions, not docs facts — merged into the rendered skill by ctx-gen and never generated. Owned by the skills maintainer.
netlify blobs:list/get/set/delete exist for inspection; the CLI
reference is their source of truth — link, don't restate.getDeployStore() or a context-specific store name for isolation.onlyIfMatch retries. That's transactional data; use Netlify DB.getDeployStore).import { getStore } from "@netlify/blobs";
import type { Context } from "@netlify/functions";
import { v4 as uuid } from "uuid";
export default async (req: Request, context: Context) => {
const form = await req.formData();
const file = form.get("file") as File;
const key = uuid();
const uploads = getStore("file-uploads");
await uploads.set(key, file, {
metadata: { country: context.geo.country.name }
});
return new Response("Submission saved");
};const uploads = getStore("json-uploads");
await uploads.setJSON(key, data, { metadata: { country: context.geo.country.name } });const uploads = getStore("file-uploads");
const entry = await uploads.get(key); // string by default
if (entry === null) {
return new Response(`Could not find ${key}`, { status: 404 });
}
return new Response(entry);const { modified } = await store.set("jane@netlify.com", "Jane Doe", { onlyIfNew: true });
if (!modified) return new Response("Email already exists", { status: 400 });const { modified } = await store.set(key, "New Jane", { onlyIfMatch: etag });
if (!modified) return new Response("Cached data is stale", { status: 400 });const { blobs } = await store.list(); // auto-paginates all pages
// blobs: [ { etag: "\"etag1\"", key: "..." }, ... ]for await (const entry of store.list({ paginate: true })) {
console.log(entry.blobs);
}const { blobs, directories } = await store.list({ directories: true }); // top level
const catList = await store.list({ directories: true, prefix: "cats/" }); // inside cats/const { stores } = await listStores(); // does NOT include deploy-specific storesawait store.delete(key); // resolves undefined
const { deletedBlobs } = await store.deleteAll(); // deletes the whole store; 0 if it didn't existimport { readFile } from "node:fs/promises";
import { getDeployStore } from "@netlify/blobs";
import { v4 as uuid } from "uuid";
export const onPostBuild = async () => {
const file = await readFile("some-file.txt", "utf8");
const uploads = getDeployStore("file-uploads");
await uploads.set(uuid(), file);
};await uploads.set(key, await req.text(), {
metadata: { expiration: new Date("2024-01-01").getTime() }
});
const entry = await uploads.getWithMetadata(key);
const { expiration } = entry.metadata;
if (expiration && expiration < Date.now()) {
await uploads.delete(key);
}const { data, etag } = await uploads.getWithMetadata("my-key", { etag: cachedETag });
if (etag === cachedETag) {
// data is null — cached copy still fresh
}const store = getStore({ name: "animals", consistency: "strong" }); // whole store
await store.get("dog", { consistency: "strong" }); // single readconst uploads = getDeployStore({ name: "file-uploads", region: "ap-southeast-2" });netlify recipes blobs-migrate YOUR_STORE_NAME