Building a JSON Formatter

We will use Claude Code as our only development tool to go from requirements to a working app. We won't use scaffolding tools like superpowers or gstack — just Claude Code and VS Code.

You can try the finished app here: JSON Formatter

Before writing any code, let's step back and think about what we're building and why.

What is JSON?#

JSON (JavaScript Object Notation) is a lightweight, text-based format for storing and exchanging structured data. Despite having "JavaScript" in its name, JSON is language-independent — virtually every programming language can read and write it. You'll encounter JSON everywhere in modern software development: API responses, configuration files, data exports, log entries, and more.

Here's a simple example of JSON:

{
  "name": "Alice",
  "age": 25,
  "hobbies": ["reading", "coding", "hiking"],
  "address": {
    "city": "San Francisco",
    "state": "CA"
  }
}

JSON organizes data using two main structures:

  • Objects — unordered collections of key-value pairs wrapped in curly braces {}. Keys are always strings, and each key is followed by a colon and its corresponding value. In the example above, "name": "Alice" is one key-value pair.
  • Arrays — ordered lists of values wrapped in square brackets []. The "hobbies" field above is an array containing three strings.

Values can be one of six types: strings (text in double quotes), numbers, booleans (true or false), null (representing "no value"), objects, or arrays. Because objects and arrays can contain other objects and arrays, JSON can represent deeply nested, tree-like structures.

This simplicity is what makes JSON so popular — it's human-readable enough to inspect by eye, yet structured enough for machines to parse reliably.

Why Do We Need a JSON Formatter?#

Although JSON is designed to be human-readable, that's only true when it's well-formatted. In practice, JSON data often arrives as a single, dense line with no whitespace or indentation. This is called minified JSON — machines produce it to save space, but it's nearly impossible for humans to read. For example, an API response might look like this:

{"users":[{"id":1,"name":"Alice","email":"alice@example.com","roles":["admin","editor"]},{"id":2,"name":"Bob","email":"bob@example.com","roles":["viewer"]}],"total":2,"page":1}

Try answering a few quick questions: How many users are there? What roles does Bob have? What is Alice's email address? It takes real effort to pick out the answers because everything is crammed onto one line with no visual structure.

Now here's the exact same data, properly formatted with indentation and line breaks:

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com",
      "roles": ["admin", "editor"]
    },
    {
      "id": 2,
      "name": "Bob",
      "email": "bob@example.com",
      "roles": ["viewer"]
    }
  ],
  "total": 2,
  "page": 1
}

The content is identical, but the formatted version is dramatically easier to scan and understand. You can immediately see the two user objects, their fields, and the overall structure.

A JSON formatter automates this transformation — it takes dense, unreadable JSON and produces clean, indented output. But formatting alone isn't enough. In daily development, you also need to:

  • Validate whether JSON is syntactically correct — a single missing comma or extra bracket makes the entire document invalid, and tracking down the mistake in a wall of text is painful
  • Minify JSON to reduce file size when sending data over the network or storing it compactly
  • Explore deeply nested structures interactively, expanding and collapsing sections to focus on the parts that matter
  • Spot errors quickly with precise locations, rather than staring at raw text trying to find what went wrong

That's the motivation for this project — we're building a JSON Formatter that handles all of these needs in one cohesive tool.

Key Features#

  1. Format (Pretty Print) — Indent JSON with configurable spacing (2 spaces, 4 spaces, or tabs) and optional alphabetical key sorting
  2. Minify — Strip all whitespace to produce the most compact output
  3. Real-Time Validation — Show whether JSON is valid or invalid as you type, with clear error messages pointing to the exact line and column
  4. Tree View — Browse JSON as a collapsible, interactive tree (like a file explorer) with type badges and click-to-copy paths
  5. Code View — View formatted JSON with syntax highlighting; switch freely between tree and code views
  6. File Upload — Load JSON from .json or .txt files instead of copy-pasting
  7. Copy & Download — One-click copy to clipboard or download as a .json file
  8. Settings — Configure indent size, key sorting, and auto-format on paste; settings persist across sessions via localStorage
  9. Statistics — Show file size, line count, key count, and max nesting depth

Quality Goals#

  • Performance — Heavy parsing runs in a background Web Worker so the UI never freezes; validation is debounced
  • Usability — Intuitive layout with clear labels, human-readable errors, and visual status indicators
  • Responsiveness — Resizable input/output panels that work on different screen sizes
  • Reliability — Handles invalid input, empty input, huge files, and edge cases without crashing

What's Next?#

With these requirements as our guide, we'll use Claude Code to build the JSON Formatter step by step — starting with writing a product requirements document (PRD).

NextProduct Requirements Document (PRD)