Why do we use JSON.stringify?

We use JSON.stringify to convert a JavaScript value into JSON text so it can be stored, logged, or sent over the network, then restored with JSON.parse when it’s received or read again. That’s the language-defined purpose of JSON.stringify, including optional replacer and spacing controls for how the output is produced (MDN: JSON.stringify).

Where JSON.stringify is useful

Sending request bodies

APIs typically accept a string body containing JSON. You create that body with JSON.stringify, and many examples set an appropriate Content-Type header:

const payload = { id: 123, title: "New item" };
await fetch("/api/items", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload)
});
// The server can parse the string with JSON.parse

See a step-by-step fetch example that stringifies a JS object before sending it to an API in this guide: freeCodeCamp: stringify before sending to an API. For broader context on message bodies, see our explainer What is a payload in a REST API?.

Persisting data in the browser

A common pattern is to stringify before saving to storage, then parse on read. MDN shows this exact flow with localStorage:

const session = { screens: [{ name: "A", width: 450 }], state: true };
localStorage.setItem("session", JSON.stringify(session));

try {
  const restored = JSON.parse(localStorage.getItem("session"));
  // restored is an object again
} catch (e) {
  // Handle malformed or unexpected JSON
}

Reference: MDN: JSON.stringify (localStorage example).

How stringify and parse work together

The practical loop is: serialize with JSON.stringify when data needs to cross a boundary (network, storage, process), then deserialize with JSON.parse on the other side. This keeps data exchange predictable across languages and services. MDN documents the core behavior of both methods and how to control output via replacer and space (MDN: JSON.stringify).

What JSON.stringify changes or omits

These behaviors are defined by the language and matter when you rely on round-trips:

• Functions, undefined, and Symbol values are not valid JSON. They are omitted in objects and become null in arrays (MDN).
• BigInt values cause a TypeError unless you provide an explicit toJSON that converts them (MDN).
• Date objects serialize as ISO 8601 strings via toJSON/toISOString (MDN).
• Only enumerable own properties are visited; Map and Set become "{}" unless you customize serialization with a replacer (MDN).
• Circular references throw a TypeError; the JSON format does not include object references (MDN).
• The space parameter pretty-prints output and is clamped/truncated to a maximum of 10 spaces/characters (MDN).

Worked examples

Filtering properties and indenting output

const obj = { name: "Ada", secret: "omit", count: 3 };
const replacer = (key, value) => (key === "secret" ? undefined : value);
const pretty = JSON.stringify(obj, replacer, 2);
// Expected result:
// {
//   "name": "Ada",
//   "count": 3
// }

Handling BigInt and Dates safely

const data = { id: 42n, when: new Date("2025-05-01T12:00:00Z") };
const out = JSON.stringify(data, (key, value) =>
  typeof value === "bigint" ? value.toString() : value
);
// Expected: {"id":"42","when":"2025-05-01T12:00:00.000Z"}

Behavior references: MDN: JSON.stringify. If you need line-delimited JSON for streaming or logs, see our explainer What are JSONL files?.

Pre-ship checklist for JSON.stringify

• Confirm the receiver expects JSON text; if sending over HTTP, include a matching Content-Type where appropriate
• Stringify before storage or transport; parse on read, wrapping JSON.parse in try/catch
• Audit values: avoid functions, undefined, symbols; decide how to represent them if needed
• Detect circular references or replace them during serialization to avoid TypeError
• Decide how to handle Dates (ISO strings by default) and BigInt (provide toJSON or convert)
• Use a replacer for Maps/Sets or other non-plain types if you need a useful JSON shape

FAQs

Is JSON.stringify a good way to deep-clone objects?

It can lose information (functions, undefined, symbols, Maps/Sets) and will throw on circular references. MDN suggests using structuredClone for deep copies, which supports circular references (MDN).

Why did JSON.stringify throw on my data?

Two common causes are circular references and BigInt values. Circular references are not supported by the JSON format, and BigInt serialization throws unless you provide a custom toJSON (MDN).