Netlify 17 ๐ Netlify Forms & Blobs โ Processing HTML form submissions and storing unstructured binary/key-value data
Static sites solved the deployment problem and created a smaller one in its place: a site with no server has nowhere to put a contact form. The obvious answer is to point the <form action> at a third-party service, which means a new account, a new API key, a new billing relationship, and a submission dataset that lives outside your project. Netlify Forms exists to remove that detour. Because Netlify already parses your HTML at deploy time, it can detect a form element, register it as a form on the site, and accept submissions at your own domain without any server code at all.
The other half of this chapter addresses where the submitted data, and any files attached to it, should go. Netlify Blobs is an unstructured storage primitive modelled on the object stores developers already know โ a store is a namespace, an object is a key and a value, and the value can be JSON, text, a stream, or raw bytes. It is deliberately not a relational database. There is no query language and no schema. What it does offer is zero provisioning, access from any function or edge function in the site, an optional strongly consistent read mode, and metadata that can be read without downloading the object body.
This chapter covers the two pieces together because they are almost always used together. The first section walks through the HTML that registers a form, the hidden form-name field that routes a submission, the honeypot and reCAPTCHA options, and the shape of the payload that arrives when the form fires an event. The second section looks at the submission-created event function that turns a form submission into arbitrary backend work. The third section examines the Blobs API in detail โ writing, reading with type coercion, metadata, listing, and deletion. Everything that follows assumes you already have a deployed site and a function directory configured.
Key point: Netlify Forms requires no server code to accept a submission โ a data-netlify="true" attribute on a deployed HTML form is the entire registration, and a hidden form-name input is what routes a POST to the right form; Netlify Blobs is the complementary unstructured store where that submission’s payload, and any files that came with it, can be persisted as keys and values.
Why exists
The static site data problem. A generated site โ Astro, Eleventy, Hugo, plain HTML โ has no request handler to receive a POST. The usual escape hatch is a form backend service or a custom function plus a database, and both add setup that dwarfs the size of the feature. Forms and Blobs exist so that a two-field contact form needs neither.
The orphaned file problem. A form that accepts a rรฉsumรฉ or a photograph returns a multipart payload that has to live somewhere. Netlify Functions have an ephemeral filesystem and a short execution window, so a file written to /tmp is gone before anyone can read it. Blobs is the sink for that data โ a key-value store that persists beyond the invocation and is reachable from any other function in the site.
The billing boundary problem. Third-party form services meter on submissions and hold the data. Blobs meters on operations and storage. Both exist to keep the operational surface inside the platform you already pay for, so there is one invoice and one access model rather than two.
The metadata problem. Storing a file is easy; finding it again is the hard part. An object store that only supports get(key) forces you to build an index somewhere else. Blobs attaches arbitrary metadata to each object โ content type, uploader, original filename โ and exposes a list operation with prefix filtering so a directory-like hierarchy can be reconstructed without a separate index.
The consistency problem. Object stores are traditionally eventually consistent, which is fine for a cache and dangerous for a session record that is written and immediately read. Blobs exposes a strong consistency mode for exactly this case, and the documentation is explicit that it requires you to supply the site identifier and access token rather than relying on automatic runtime configuration.
The portability problem. Blob store APIs are usually tied to one vendor’s SDK and one vendor’s authentication model. Netlify Blobs is a thin client over S3-compatible semantics, and its API surface is small enough that a mock is trivial โ which matters more for testing than for migration.
a. Netlify Forms โ registration, markup, and submission routing
Forms are registered at deploy time, not at runtime. When Netlify’s build step processes the deploy, it parses the HTML files and every form element carrying data-netlify="true" or a netlify attribute becomes a registered form, named by its name attribute. Nothing about that step is dynamic: a form that is not in the deployed HTML does not exist, and this is the single most common source of confusion when a form “isn’t showing up” in the dashboard.
<!-- index.html โ parsed at deploy time, so this must be in the built output -->
<form
name="contact"
method="POST"
data-netlify="true"
netlify-honeypot="bot-field"
>
<!-- The hidden field tells Netlify which registered form this POST belongs to -->
<input type="hidden" name="form-name" value="contact" />
<!-- Bots fill every field they find; humans never see this one -->
<p hidden>
<label>Leave this empty: <input name="bot-field" /></label>
</p>
<label>Name <input type="text" name="name" required /></label>
<label>Email <input type="email" name="email" required /></label>
<button type="submit">Send</button>
</form>
The name attribute on the form and the value of the hidden form-name input must agree. That hidden input is what disambiguates a submission when a page carries several forms, and it is mandatory for any submission sent programmatically โ a fetch POST with no form-name field will be rejected because Netlify has no way to attribute it.
The netlify-honeypot attribute names a field that must arrive empty. If a bot fills it, the submission is filed as spam rather than delivered. Netlify also runs Akismet-style content filtering and, on paid tiers, offers reCAPTCHA 2 integration by adding data-netlify-recaptcha="true" to the form and the corresponding widget to the markup.
Single-page applications need special handling because the form is rendered by JavaScript and therefore invisible at deploy time. The workaround is a hidden static copy of the form in the built HTML whose only purpose is registration, followed by a programmatic POST.
<!-- public/__forms.html โ never rendered, exists only so the build registers the form -->
<html>
<body>
<form name="contact" data-netlify="true" hidden>
<input type="hidden" name="form-name" value="contact" />
<input name="name" /><input name="email" /><textarea name="message"></textarea>
</form>
</body>
</html>
// Sending from the client after the form is registered
await fetch("/", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
// URLSearchParams encodes the object the way an HTML form would
body: new URLSearchParams({ "form-name": "contact", name, email, message }),
});
File uploads change the encoding rather than the routing. A form with enctype="multipart/form-data" and an <input type="file" name="attachment"> sends the file with the submission, and it becomes a download link in the Netlify UI. The same form-name field is still required, and the encoding must be multipart/form-data on the fetch as well โ you cannot express a file in URLSearchParams.
<!-- Multipart form with a file field -->
<form name="application" method="POST" data-netlify="true" enctype="multipart/form-data">
<input type="hidden" name="form-name" value="application" />
<input type="text" name="full_name" required />
<input type="file" name="resume" accept=".pdf" required />
<button type="submit">Apply</button>
</form>
Submissions are visible in the Netlify dashboard under the Forms tab, where each form lists its submissions with the field values and any uploaded files. The free tier includes 100 submissions per month; paid tiers raise that ceiling, and the dashboard warns as you approach it. Production sites that expect a high volume should plan for the transition from “read it in the UI” to “forward it somewhere” before they hit the limit.
b. The submission-created event function
Reading submissions in a dashboard does not scale to a real product. Netlify emits an event called submission-created every time a form is submitted, and a function named exactly submission-created (in the forms directory โ netlify/functions/submission-created.ts by default) receives it. This is the hook where a submission becomes persistence, notification, or enrichment.
// netlify/functions/submission-created.ts
import type { Handler } from "@netlify/functions";
import { getStore } from "@netlify/blobs";
export const handler: Handler = async (event) => {
// The event body is a JSON string with a `payload` object
const { payload } = JSON.parse(event.body ?? "{}");
// form_name tells you which registered form fired the event
if (payload.form_name !== "contact") return { statusCode: 200 };
const store = getStore("submissions");
// data holds the submitted field values, keyed by input name
await store.setJSON(`contact/${payload.id}.json`, {
fields: payload.data,
createdAt: payload.created_at,
formId: payload.form_id,
});
return { statusCode: 200, body: "stored" };
};
The payload is worth knowing in detail because it is not quite what a form submitter would expect. payload.data is a flat object of field name to value. payload.human_fields is a friendlier map with the labels as keys and the values as an array, which is useful when you are forwarding to an email template. payload.ordered_human_fields preserves the markup order so a rendered email reads the way the form does. payload.id is a unique identifier you can use as a blob key, and payload.created_at is an ISO timestamp.
The return value of this function barely matters โ Netlify has already accepted the submission and the user has already been redirected. A non-200 response is logged but does not roll back the submission, which is important to understand: this handler is a side effect, not a transaction. If your storage write fails, the data still exists in the Netlify UI, and you have to reconcile it manually.
Because the event function runs in the same function runtime as everything else, it can do anything a function can do. The common patterns are: persist the submission to Blobs or an external API, post a message to Slack, append to a Google Sheet, or send a transactional email. It can also read the file uploads, which arrive in the payload as URLs that the function can fetch.
// Forwarding a submission to an external CRM
const res = await fetch("https://crm.example.com/api/leads", {
method: "POST",
headers: {
"Content-Type": "application/json",
// The secret comes from the function environment, never the client
Authorization: `Bearer ${process.env.CRM_TOKEN}`,
},
body: JSON.stringify({
name: payload.data.name,
email: payload.data.email,
source: `netlify:${payload.form_name}`,
receivedAt: payload.created_at,
}),
});
// Log rather than throw: a failed forward must not look like a failed submission
if (!res.ok) console.error("CRM rejected lead", res.status, await res.text());
Notification settings in the dashboard cover the simple case โ an email to an address, a Slack message, or an outgoing webhook โ and the event function covers everything else. Most sites use the dashboard for human notification and the function for machine persistence, because the dashboard route requires no code and the function route requires no human.
c. Netlify Blobs โ keys, values, metadata, and listing
Blobs is organised as stores containing objects. A store is a namespace you create implicitly by naming it, and it is scoped to the site. getStore is the only entry point.
import { getStore } from "@netlify/blobs";
// The store is created on first write; naming it is all the setup there is
const store = getStore("uploads");
// Values can be strings, buffers, streams, or anything setJSON accepts
await store.set("notes/hello.txt", "Hello, blobs");
// The read returns a string by default
const text = await store.get("notes/hello.txt"); // "Hello, blobs"
// JSON has a dedicated pair of helpers so you never stringify by hand
await store.setJSON("config/site.json", { theme: "dark", locale: "en" });
const config = await store.get("config/site.json", { type: "json" });
// Binary values round-trip through an arrayBuffer
await store.set("images/logo.png", buffer);
const bytes = await store.get("images/logo.png", { type: "arrayBuffer" });
The type option on get is the read-side coercion. It accepts "text" (the default), "json", "arrayBuffer", "blob", and "stream". Choosing "stream" matters for large objects because it avoids buffering the whole body in the function’s memory โ the stream can be piped straight into a response, which is how a download endpoint works.
Metadata is the feature that separates a functional store from a bare one. Every object can carry a small set of key-value strings that are readable without transferring the object body, and getWithMetadata returns both in one round trip.
// Attach descriptive metadata at write time
await store.set("uploads/report.pdf", pdfBytes, {
metadata: {
contentType: "application/pdf",
originalName: "q3-report.pdf",
uploadedBy: "user_482",
},
});
// Read the body and the metadata together
const { data, metadata } = await store.getWithMetadata("uploads/report.pdf", {
type: "arrayBuffer",
});
// Metadata alone, useful for a listing page that must not download every file
const metaOnly = await store.getMetadata("uploads/report.pdf");
Listing returns an asynchronous iterator, and it supports a prefix for the directory illusion plus a directories flag that changes the shape of the result from a flat stream of keys to entries grouped by level.
// Prefix filtering: everything under uploads/2024/
for await (const entry of store.list({ prefix: "uploads/2024/" })) {
console.log(entry.key, entry.etag, entry.metadata);
}
// Directory mode: one level at a time, like `ls` rather than `find`
const { blobs, directories } = await store.list({ directories: true, prefix: "uploads/" });
// blobs holds the objects at this level; directories holds the sub-prefixes
console.log(blobs.map((b) => b.key), directories);
Deletion is a single call and is idempotent โ deleting a key that does not exist is not an error, which makes it safe to call from a cleanup routine that may run twice.
// Safe to call even if the key was already removed
await store.delete("uploads/old-report.pdf");
The consistency question deserves its own paragraph. Reads are eventually consistent by default, which means a write followed immediately by a read may return stale data. For a session record or a lock, that is unacceptable, and the fix is to open the store in strong mode. Strong mode requires explicit credentials because it routes through a different endpoint, and the documentation is clear that automatic configuration supplies neither the site ID nor the token.
// Strong consistency: reads reflect the last completed write
const strict = getStore({
name: "sessions",
consistency: "strong",
siteID: process.env.NETLIFY_SITE_ID,
token: process.env.NETLIFY_BLOBS_TOKEN,
});
await strict.setJSON("session/abc", { userId: 482, expires: Date.now() + 3600_000 });
const session = await strict.get("session/abc", { type: "json" });
There is also a deploy-scoped variant where a store belongs to a specific deploy rather than the site, passed as deploy in the options and useful for build artefacts or content that ships with a release. Everything else about the API is unchanged, which keeps the mental model small: a store is a namespace, an object is a key and a value, metadata is a small annotation, and listing is the only query surface.
Complete Example Session
// ============================================
// PART 1: THE FORM โ DEPLOY-TIME REGISTRATION
// ============================================
// public/apply.html
// <form name="application" method="POST" data-netlify="true"
// enctype="multipart/form-data" netlify-honeypot="bot-field">
// <input type="hidden" name="form-name" value="application" />
// <p hidden><input name="bot-field" /></p>
// <input name="full_name" required />
// <input type="email" name="email" required />
// <input type="file" name="resume" accept=".pdf" required />
// <button>Apply</button>
// </form>
// ============================================
// PART 2: THE SPA REGISTRATION STUB
// ============================================
// A hidden static copy so the build registers the form even though the
// real one is rendered by React and therefore invisible to the parser.
export const RegistrationStub = () => (
<form name="application" data-netlify="true" hidden>
<input type="hidden" name="form-name" value="application" />
<input name="full_name" /><input name="email" /><input type="file" name="resume" />
</form>
);
// ============================================
// PART 3: THE CLIENT SUBMIT โ MULTIPART
// ============================================
async function submitApplication(form: HTMLFormElement) {
// FormData preserves the file field; URLSearchParams cannot
const body = new FormData(form);
body.append("form-name", "application"); // route the POST to the right form
const res = await fetch("/", { method: "POST", body });
return res.ok;
}
// ============================================
// PART 4: THE EVENT FUNCTION
// ============================================
// netlify/functions/submission-created.ts
import type { Handler } from "@netlify/functions";
import { getStore } from "@netlify/blobs";
export const handler: Handler = async (event) => {
const { payload } = JSON.parse(event.body ?? "{}");
if (payload.form_name !== "application") return { statusCode: 200 };
// ============================================
// PART 5: PERSISTING THE FIELDS
// ============================================
const store = getStore("applications");
const key = `applications/${payload.id}.json`;
await store.setJSON(key, {
fields: payload.data, // flat map of input name -> value
submittedAt: payload.created_at,
formId: payload.form_id,
});
// ============================================
// PART 6: STORING THE UPLOADED FILE
// ============================================
const resumeEntry = payload.human_fields?.Resume;
if (resumeEntry) {
// The payload carries a URL for each uploaded file
const fileRes = await fetch(Array.isArray(resumeEntry) ? resumeEntry[0] : resumeEntry);
const bytes = await fileRes.arrayBuffer();
await store.set(`resumes/${payload.id}.pdf`, bytes, {
metadata: {
contentType: "application/pdf",
applicantEmail: payload.data.email,
originalName: "resume.pdf",
},
});
}
return { statusCode: 200 };
};
// ============================================
// PART 7: A DOWNLOAD ENDPOINT
// ============================================
// netlify/functions/download.ts
import type { Handler } from "@netlify/functions";
export const download: Handler = async (event) => {
const id = event.queryStringParameters?.id;
if (!id) return { statusCode: 400, body: "missing id" };
const store = getStore("applications");
const { data, metadata } = await store.getWithMetadata(`resumes/${id}.pdf`, {
type: "arrayBuffer",
});
if (!data) return { statusCode: 404, body: "not found" };
return {
statusCode: 200,
headers: {
"Content-Type": metadata?.contentType ?? "application/octet-stream",
"Content-Disposition": `attachment; filename="${metadata?.originalName ?? "file"}"`,
},
body: Buffer.from(data).toString("base64"),
isBase64Encoded: true, // required for binary response bodies
};
};
// ============================================
// PART 8: LISTING FOR AN ADMIN VIEW
// ============================================
async function listApplications() {
const store = getStore("applications");
const out: string[] = [];
// Prefix keeps JSON records and PDF blobs from mixing
for await (const { key, metadata } of store.list({ prefix: "applications/" })) {
out.push(key);
}
return out;
}
// ============================================
// PART 9: STREAMING A LARGE OBJECT
// ============================================
async function streamLargeObject(key: string) {
const store = getStore("uploads");
// "stream" avoids buffering the whole body in function memory
const stream = await store.get(key, { type: "stream" });
return new Response(stream);
}
// ============================================
// PART 10: STRONG CONSISTENCY FOR A SESSION
// ============================================
const sessions = getStore({
name: "sessions",
consistency: "strong", // read-after-write is guaranteed
siteID: process.env.NETLIFY_SITE_ID,
token: process.env.NETLIFY_BLOBS_TOKEN,
});
await sessions.setJSON("s/abc", { userId: 482, seenAt: Date.now() });
const s = await sessions.get("s/abc", { type: "json" }); // never stale
The ten parts covered the deploy-time form markup, the SPA registration stub, a multipart client submit, the submission-created handler, field persistence, file storage with metadata, a binary download endpoint, prefix listing, streaming reads, and the strong-consistency session store.
Quick Reference
Form Registration Attributes
| Attribute | Placed On | Purpose |
|---|---|---|
data-netlify="true" | <form> | Registers the form at deploy time |
name | <form> | The registered form’s identifier |
form-name | hidden input | Routes a POST to that identifier |
netlify-honeypot | <form> | Names the field bots must leave empty |
data-netlify-recaptcha | <form> | Enables the reCAPTCHA widget |
enctype="multipart/form-data" | <form> | Required for file uploads |
The submission-created Payload
| Field | Content |
|---|---|
payload.data | Flat map of input name to submitted value |
payload.human_fields | Label-keyed map, values as arrays |
payload.ordered_human_fields | Same, in markup order |
payload.id | Unique submission identifier |
payload.form_name | Which form fired the event |
payload.created_at | ISO timestamp of submission |
Blobs API Surface
| Call | Returns |
|---|---|
store.set(key, value, opts) | { modified, etag } |
store.get(key, { type }) | Value coerced to type |
store.setJSON(key, obj) | Stores object as JSON |
store.getWithMetadata(key) | { data, metadata } |
store.list({ prefix, directories }) | Async iterable of entries |
store.delete(key) | Nothing; idempotent |
Read Types and Consistency
| Option | Values | Effect |
|---|---|---|
type | text, json, arrayBuffer, blob, stream | Coercion on read |
consistency | eventual (default), strong | Read-after-write guarantee |
| Credentials | siteID, token | Required for strong mode |
deploy | deploy identifier | Deploy-scoped store |
Best Practices
โ Do This:
// Always include the routing field
body.append("form-name", "contact"); // โ
// Use FormData when a file is involved
const body = new FormData(form); // โ
// Store the event id as part of the key
await store.setJSON(`applications/${payload.id}.json`, data); // โ
// Attach metadata so listing needs no extra fetch
await store.set("f.pdf", bytes, { metadata: { contentType: "application/pdf" } }); // โ
// Stream large objects instead of buffering
await store.get(key, { type: "stream" }); // โ
// Use strong consistency for sessions and locks
getStore({ name: "sessions", consistency: "strong", siteID, token }); // โ
โ Don’t Do This:
// Omit form-name on a programmatic POST
await fetch("/", { method: "POST", body: new URLSearchParams({ name }) }); // โ
// Register a form rendered only by client-side JS
// (the parser never sees it) // โ
// Rely on read-after-write without strong consistency
await store.setJSON(k, v); await store.get(k); // โ
// Download a whole object just to read its content type
const bytes = await store.get(key); // โ
// Throw from the event function expecting a rollback
throw new Error("forward failed"); // โ
// Assume `/tmp` persists between invocations
writeFileSync("/tmp/x", data); // โ
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Form missing from dashboard | Rendered by client-side JS only | Add a hidden static copy to the build |
| Submission returns 404 | form-name field omitted | Add the hidden input and send it |
| File arrives empty | Form lacks multipart/form-data | Set enctype and send FormData |
| Stale read after write | Default eventual consistency | Open the store with consistency: "strong" |
| Strong mode throws | siteID or token not supplied | Pass both explicitly from env vars |
list() returns everything | No prefix given | Filter with prefix: "uploads/2024/" |
| Function times out on big files | Body buffered in memory | Read with type: "stream" |
| Data lost after a bad forward | Event handler is not transactional | Log the failure and reconcile from the UI |
Real-World Examples
1. Honeypot-protected contact form
<form name="contact" method="POST" data-netlify="true" netlify-honeypot="bot-field">
<input type="hidden" name="form-name" value="contact" />
2. SPA fetch submit
await fetch("/", { method: "POST", body: new URLSearchParams({ "form-name": "signup", email }) });
3. Resume upload form
<form name="job" data-netlify="true" enctype="multipart/form-data" method="POST">
4. Routing the event by form name
if (payload.form_name !== "newsletter") return { statusCode: 200 };
5. Storing a submission as JSON
await store.setJSON(`subs/${payload.id}.json`, payload.data);
6. Caching a rendered page
await store.set(`html/${slug}.html`, html, { metadata: { renderedAt: new Date().toISOString() } });
7. Listing a user’s files
for await (const e of store.list({ prefix: `users/${id}/` })) keys.push(e.key);
8. Binary download endpoint
body: Buffer.from(await data).toString("base64"), isBase64Encoded: true,
9. Strong-consistent rate limiter
const counter = (await limiter.get(key, { type: "json" })) ?? { n: 0 };
10. Deploy-scoped content store
const store = getStore({ name: "content", deploy: process.env.DEPLOY_ID });
Visual
The Form Submission Path
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ BUILD TIME โ
โ HTML scanned โโโบ <form data-netlify="true"> found โ
โ name="contact" โโโบ form registered โ
โ โ
โ RUNTIME โ
โ browser POST โโโบ form-name=contact โโโบ routed to form โ
โ honeypot empty? โโโบ spam queue โ
โ reCAPTCHA ok? โโโบ accepted โ
โ โ โ
โ โโโโโโโโโโโโโโโโโโดโโโโโโโโโโโ โ
โ โผ โผ โ
โ dashboard + email submission- โ
โ notification created fn โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Where the Data Goes
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ submission-created event โ
โ payload.data โโโโโโโโโโโบ Blobs: subs/{id}.json โ
โ payload.human_fields.Resume โโโบ fetch โโโบ Blobs โ
โ resumes/ โ
โ {id}.pdf โ
โ โ
โ both share one store, separated by prefix โ
โ โ
โ applications/ โโโบ JSON records โ
โ resumes/ โโโบ binary objects + metadata โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Eventual vs Strong Consistency
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ EVENTUAL (default) โ
โ set(k) โโโบ replica A โ
โ get(k) โโโบ replica B โโโบ may return null (stale) โ
โ โ
โ STRONG (siteID + token supplied) โ
โ set(k) โโโบ primary โโโบ acknowledged โ
โ get(k) โโโบ primary โโโบ always the last completed write โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Listing with Prefix and Directories
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ STORE "applications" โ
โ applications/1.json โ
โ applications/2.json โ
โ resumes/1.pdf โ
โ resumes/2.pdf โ
โ โ
โ list({ prefix: "applications/" }) โโโบ 2 entries โ
โ list({ directories: true }) โโโบ โ
โ directories: ["applications/", "resumes/"] โ
โ blobs: [] โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Summary
| Item | Value |
|---|---|
| Registration attribute | data-netlify="true" on the <form> |
| Routing field | hidden form-name input |
| Spam control | netlify-honeypot attribute, reCAPTCHA |
| File uploads | enctype="multipart/form-data" |
| Event hook | submission-created function |
| Client library | @netlify/blobs |
| Entry point | getStore(name) |
| Read types | text, json, arrayBuffer, blob, stream |
| Metadata | Small string map, readable without the body |
| Consistency | Eventual by default, strong with credentials |
| Scoping | Site-scoped by default, deploy for per-deploy |
Key takeaways:
- Forms are registered at deploy time, not at runtime. The HTML parser in the build step is what discovers a form, so any form rendered solely by client-side JavaScript needs a hidden static copy in the built output.
- The hidden
form-namefield is the router. A programmatic POST without it has no form to belong to and is rejected, which is the most common cause of a submission that “does nothing.” - File uploads require multipart encoding end to end. The form attribute, the client
FormDataobject, and the function’s handling of the payload all have to agree, and a mismatch shows up as an empty file rather than an error. submission-createdis a side effect, not a transaction. Netlify has already stored the submission by the time your handler runs, so throwing from it does not roll anything back โ log the failure and reconcile.- Blobs is a key-value store, not a database. There is no query language;
listwith a prefix is the only lookup mechanism, so keys should be designed as paths from the start. - Metadata is what makes listing useful. Content type, original filename, and owner can all be read without downloading the object, which turns a listing page into a single cheap operation.
- Consistency is opt-in. Eventual reads are the default and are fine for caches; a session or a lock needs
consistency: "strong"plus the explicitsiteIDandtoken.
Remember: The pairing of Forms and Blobs is a static site’s backend in miniature. The form supplies the ingress โ an HTML element the build recognises, a hidden field that routes the POST, and an event that fires once the submission is safely stored. Blobs supplies the egress โ a store you name into existence, objects addressed by path-like keys, metadata that makes those keys searchable, and a strong consistency mode for the handful of reads that cannot tolerate staleness. Design the keys first, wrap every side effect in the event function in a try/catch, and the whole pipeline stays as simple as the static site it sits behind.
Stop using slow, ad-bloated tool sites! ๐คฎ
๐ Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
โ
Finance (Mortgage, Interest, Inflation)
โ
Tech (Base64, JSON, Dev Suite, IP)
โ
Health (BMI, BMR, TDEE)
โ
Productivity (Timer, Workspace, QR)
โก๏ธ Fast & Private
๐ No data leaves your device
๐ 100% Free
๐ Use it now: https://tools.kandz.me
๐ Bookmark itโyouโll need it later!