netlify-blobs

Netlify Blobs

Modern import — reach for this:

import { getStore, getDeployStore, listStores } from "@netlify/blobs";

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):

const store = getStore("file-uploads");                          // string form
const store = getStore({ name: "animals", consistency: "strong" }); // options form

siteID, token, deployID, and region are set automatically inside Functions, Edge Functions, and Build Plugins — do not pass them manually there.

Choosing the store type — READ THIS FIRST

• 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.

Common tasks

Persist a user upload with metadata (set)

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");
};