Embedding JSON Formatters in Custom Applications

JSON (JavaScript Object Notation) has become the de facto standard for data interchange on the web and in many other applications. While developers often interact with JSON via APIs or configuration files, there are many scenarios where presenting JSON data in a human-readable, formatted way directly within a custom application is highly beneficial. This article explores the concepts and approaches to embedding JSON formatters into your own software.

Why Embed a JSON Formatter?

Embedding a JSON formatter allows you to display raw JSON data cleanly and structure within your application's user interface. This is particularly useful for:

• Debugging and Inspection: Allowing users or developers to view the exact structure and content of JSON payloads received from APIs or generated internally.
• Configuration Editors: Providing a user-friendly way to edit application settings stored in JSON format.
• Data Visualization Prep: Displaying complex data structures before processing or visualization.
• Educational Tools: Helping users understand the structure of JSON.

A well-formatted JSON string includes indentation, line breaks, and consistent spacing, making nested objects and arrays easy to follow.

What Does "Formatting" Involve?

At its core, JSON formatting involves taking a raw JSON string and producing a new string that represents the same data but with added whitespace (spaces, tabs, newlines) to improve readability. The standard pretty-printing typically follows rules like:

• Each key-value pair in an object is on a new line.
• Each element in an array is on a new line.
• Nested objects and arrays are indented further than their parent.
• A colon (`:`) separating a key and value is followed by a space.
• Commas (`,`) separating items are followed by a newline.

Optionally, formatting can also include:

• Syntax highlighting (coloring keys, strings, numbers, booleans, etc.).
• Collapsible sections for objects and arrays.
• Line numbers.

While the advanced features often require parsing the JSON into a data structure and then recursively rendering elements, basic indentation can sometimes be achieved directly via string manipulation or built-in functions.

Approaches to Embedding a Formatter

1. Using Built-in Functions (`JSON.stringify`)

The simplest approach in JavaScript environments (including browsers and Node.js) is to leverage the native `JSON.stringify()` method, which includes optional parameters for formatting.

The signature is typically `JSON.stringify(value, replacer, space)`. The `space` parameter is key for formatting.

const rawJsonString = '{"name":"Alice","age":30,"isStudent":false,"courses":["Math","Science"],"address":null}';

try {
  // First, parse the string into a JavaScript object/array
  const jsonObj = JSON.parse(rawJsonString);

  // Then, stringify it back with formatting
  // The third argument (2) is the number of spaces for indentation
  const formattedJsonString = JSON.stringify(jsonObj, null, 2);

  console.log("--- Raw JSON ---");
  console.log(rawJsonString);
  console.log("\n--- Formatted JSON (2 spaces) ---");
  console.log(formattedJsonString);

  // You can also use a string for indentation, e.g., '\t' for tabs
  const formattedJsonStringWithTabs = JSON.stringify(jsonObj, null, '\t');
  console.log("\n--- Formatted JSON (Tabs) ---");
  console.log(formattedJsonStringWithTabs);

} catch (error) {
  console.error("Error parsing or stringifying JSON:", error.message);
}

This method is excellent for basic indentation and is built-in, requiring no external code. However, it doesn't provide features like syntax highlighting or collapsibility out of the box. To display this formatted string in a web page, you would typically put it inside a `<pre>` tag to preserve whitespace.

2. Building a Custom Formatter

If you need more advanced features like syntax highlighting, collapsibility, or specific handling of data types, you'll need to build a custom formatter. This involves:

• Parsing: Use `JSON.parse()` to convert the raw JSON string into a JavaScript object or array.
• Traversing: Recursively walk through the parsed data structure (objects and arrays).
• Rendering/Formatting: As you traverse, build the output string or a structure that represents the formatted JSON. This is where you apply indentation, add syntax highlighting classes (if rendering HTML), and potentially add markers for collapsibility.

function formatValue(value, indentLevel) {
  const indent = '  '.repeat(indentLevel); // Using 2 spaces for example

  if (value === null) {
    return `${indent}null`; // Add class for 'null' highlighting
  }

  const type = typeof value;

  if (type === 'number' || type === 'boolean') {
    return `${indent}${value}`; // Add class for number/boolean highlighting
  }

  if (type === 'string') {
    // Escape quotes and backslashes in the string itself
    const escapedString = JSON.stringify(value);
    return `${indent}${escapedString}`; // Add class for string highlighting
  }

  if (Array.isArray(value)) {
    if (value.length === 0) {
        return `${indent}[` + /* optional collapse icon */ + `]`;
    }
    const elements = value.map(item =>
      formatValue(item, indentLevel + 1).trimStart() // Format element, then remove its leading indent
    );
    return `${indent}[` + /* optional collapse icon */ + `\n${elements.join(',\n')}\n${indent}]`;
  }

  if (type === 'object') {
    const keys = Object.keys(value);
    if (keys.length === 0) {
        return `${indent}{` + /* optional collapse icon */ + `}`;
    }
    const entries = keys.map(key => {
      const formattedKey = JSON.stringify(key); // Keys are always strings in JSON
      const formattedValue = formatValue(value[key], indentLevel + 1);
      return `${indent}  ${formattedKey}: ${formattedValue.trimStart()}`; // Add class for key highlighting
    });
    return `${indent}{` + /* optional collapse icon */ + `\n${entries.join(',\n')}\n${indent}}`;
  }

  // Should not happen with valid JSON, but handle other types
  return `${indent}UnsupportedType`;
}

function customJsonFormatter(jsonString) {
    try {
        const data = JSON.parse(jsonString);
        // Start formatting from the root value with indent level 0
        return formatValue(data, 0);
    } catch (error) {
        return `Error parsing JSON: ${error.message}`;
    }
}

// Example Usage (Conceptual):
// const jsonInput = '{"user":{"name":"Bob","age":25},"items":[10,true,null],"active":true}';
// const formattedOutput = customJsonFormatter(jsonInput);
// console.log(formattedOutput); // Output the manually formatted string

This conceptual example shows the recursive nature of traversing the structure and building the output string with indentation. In a real application displaying HTML, instead of returning a string, you might return JSX elements, applying CSS classes for colors and adding elements like `<span>` with click handlers for collapsing sections.

Implementing syntax highlighting involves wrapping different parts of the output (keys, strings, numbers, booleans, null, punctuation like {, }, [, ], :, ,) in HTML elements (like `<span>`) with specific CSS classes (e.g., `.json-key`, `.json-string`, `.json-number`).

3. Leveraging Existing Libraries (Conceptually)

While this article focuses on embedding *without* external libraries (except Lucide for icons), it's important to know that many robust, feature-rich JSON viewer/formatter libraries exist for various frameworks (React, Vue, Angular) and vanilla JavaScript. These libraries handle parsing, traversal, rendering, syntax highlighting, collapsibility, search, and large file performance complexities for you.

If you were allowed to use them, integrating such a library would typically involve installing it and passing your JSON data (either as a string or parsed object) to a component or function provided by the library. This saves significant development time but adds an external dependency.

Displaying the Output

Once you have the formatted JSON string (either from `JSON.stringify` or your custom formatter), displaying it in your application interface is crucial.

• For simple formatting: Use the `<pre>` tag to preserve whitespace and line breaks. Inside `<pre>`, use a `<code>` tag.
• For custom formatting with HTML/JSX: The custom formatter would directly generate JSX elements (e.g., nested `<div>`s, `<span>`s with classes). Render these elements directly in your component. You'd likely need CSS to style the indentation and syntax highlighting colors.

// Assume formattedJsonString contains the output from JSON.stringify(..., 2)
// or a string from a custom formatter that produces plain text output with newlines/spaces

<div className="json-container bg-neutral-50 dark:bg-neutral-800 p-4 rounded">
  <pre className="text-sm overflow-x-auto">
    <code>
      {/* Render the pre-formatted string */}
      {`{\n  "name": "Alice",\n  "age": 30,\n  "isStudent": false,\n  "courses": [\n    "Math",\n    "Science"\n  ],\n  "address": null\n}`}
    </code>
  </pre>
</div>

{/* Example if your custom formatter produced JSX directly */}
{/* This would require a different structure where formatValue returns JSX, not a string */}
{/*
<div className="json-container">
  <div style={{ marginLeft: '0px' }}>
    <span className="json-punctuation">{</span>
    <br/>
    <div style={{ marginLeft: '20px' }}>
      <span className="json-key">"name"</span>
      <span className="json-punctuation">: </span>
      <span className="json-string">"Alice"</span>
      <span className="json-punctuation">,</span>
      <br/>
      <span className="json-key">"age"</span>
      <span className="json-punctuation">: </span>
      <span className="json-number">30</span>
      <span className="json-punctuation">,</span>
      <br/>
      // ... more elements ...
    </div>
    <span className="json-punctuation">}</span>
  </div>
</div>
*/}

When building a custom formatter that outputs JSX, you need to carefully manage indentation using CSS (like `marginLeft`) and apply different classes for different JSON data types to style them visually. Handling large JSON can become a performance consideration with custom formatters, potentially requiring virtualization or lazy rendering techniques.

Conclusion

Embedding a JSON formatter into your custom application can significantly enhance the user or developer experience when dealing with JSON data. For basic needs, the built-in `JSON.stringify` with the `space` parameter offers a simple and effective solution. For more advanced features like syntax highlighting and collapsibility, a custom formatter built by parsing and recursively traversing the JSON structure is necessary. While building a custom formatter requires more effort, it gives you complete control over the presentation. Understanding these approaches allows you to choose the right method based on the complexity and features required for your specific application's needs.