How to Use the Json To Ndjson: Step-by-Step Tutorial

The JSON to NDJSON Converter runs entirely in your browser — your JSON file is never sent to any server, no account is required, and nothing leaves your machine. This tutorial walks through every step of using the tool: choosing an input mode, loading or pasting JSON, running the conversion, reading the stats panel, previewing the output, and downloading the result. It also covers the edge cases you are most likely to encounter and explains how the tool handles each one.

Connect on LinkedIn →

Step 1 — Open the Tool

Navigate to /developer-tools/json-to-ndjson/. The tool loads entirely in the browser — after the initial page load, converting a file makes zero outbound network requests. You can confirm this in your browser's DevTools Network panel: drop a file and watch the network tab remain idle while the conversion runs.

The tool is accessible from the Developer Tools hub, the command palette (press Ctrl+K or ⌘K and type "JSON to NDJSON"), or directly via the URL above.

Step 2 — Choose an Input Mode

The tool box has two tabs at the top: File and Paste. Click whichever tab matches how you want to provide your JSON.

• File mode is the default. Use it when your JSON is in a .json file on disk. It accepts files up to 200 MB, making it appropriate for large database exports, API dumps, and machine learning datasets.
• Paste mode is faster for small snippets — an API response copied from a browser DevTools panel, a JSON example from documentation, or a test fixture. There is no size limit enforced on the text area, but very large pastes may slow the browser; for files over a few megabytes, File mode is more reliable.

If you are unsure which to use, start with File mode. If you want to quickly convert a small snippet without saving it to disk first, use Paste mode.

Step 3a — Upload a JSON File

In File mode, load your JSON in one of two ways:

• Drag and drop. Drag your .json file from your file manager, desktop, or Downloads folder and drop it anywhere on the drop zone. The drop zone highlights when a file is dragged over it. Once dropped, the filename and file size appear in a bar below the drop zone.
• Click to browse. Click the drop zone or the "browse" link inside it to open your operating system's file picker. Navigate to the file and select it. The filename bar appears as soon as the file is selected.

To clear the loaded file and load a different one, click the ✕ button in the filename bar. The tool resets to its initial state, ready for a new file.

Step 3b — Paste JSON Directly

In Paste mode, click inside the text area and type or paste your JSON. The text area accepts any JSON: compact single-line, pretty-printed multi-line, or anything in between. Whitespace in the input does not affect the output — the converter calls JSON.parse() on the entire input text, then re-serializes each element with JSON.stringify(), so the output is always compact regardless of the input formatting.

To clear the text area and start over, click the Clear button beneath it.

Step 4 — Run the Conversion

Once your input is loaded or pasted, click the Convert to NDJSON button. The conversion runs in JavaScript in your browser tab. For most files under a few megabytes, results appear within a second. For very large files — 50 MB or more — the conversion may take a few seconds; the button disables during processing to prevent double-clicks.

The conversion validates the input first by calling JSON.parse(). If the input is not valid JSON, an error message appears describing the syntax problem — no output is produced until the input parses correctly. Fix the error in your file or paste, then click Convert again. Clicking Convert also clears any output from a previous run, so you can convert multiple files in sequence without reloading the page.

Step 5 — Read the Stats Panel

After a successful conversion, a stats panel appears below the button. It reports:

• Records. The number of elements in the top-level array — this is the number of lines in the NDJSON output. Compare this against the expected record count from your source system. A mismatch means the export was truncated or the JSON is nested inside an outer object.
• Output size. The size of the NDJSON output in bytes, kilobytes, or megabytes. Compare this against the original file size to understand the compression effect of removing indentation and reformatting to one object per line.
• Input type. Whether the top-level JSON value was an array, a single object, or a primitive value. An array is the normal case. A warning is shown if the input is not an array.

If any warnings are present — input is a single object, input is an empty array, input is a primitive — they appear in this panel. Warnings do not prevent the output from being downloaded, but they signal that the input may not be what was intended.

Step 6 — Preview the Output

Below the stats panel, a preview panel shows the first five lines of the NDJSON output. Each line is the compact JSON serialization of one array element, with all whitespace removed. Scan the preview to confirm:

• The right fields appear in the first few records
• Values look correct — strings are quoted, numbers are unquoted, nested objects appear as embedded JSON
• No unexpected characters appear at the start or end of any line

The preview is truncated to 5 lines for readability. To inspect more records, download the output file and open it in a text editor. For large files, a command-line tool like head -20 output.ndjson will show the first 20 records.

Step 7 — Download the Result

Click the Download .ndjson button to save the output file. The file is named by replacing the .json extension of the input file with .ndjson. For pasted input, the file is named pasted-input.ndjson. The download goes to your browser's default download folder.

After downloading, verify the file in your destination system before using it in production. For Elasticsearch, run a test _bulk request with the first few lines. For BigQuery, run a dry-run load job. For Spark or DuckDB, read the first 100 records and confirm the schema looks correct. The stats panel's record count should match the row count you see in the destination system.

Edge Cases and How the Tool Handles Them

Single JSON object as input. If your JSON is a single object rather than an array — for example, {"data": [...], "meta": {...}} — the converter writes a single-line NDJSON file containing that one object and shows a warning. This is usually not the intended behavior. Inspect the JSON to find the inner array (likely the data key in the example above) and extract it before converting. In JavaScript: JSON.stringify(input.data) produces the inner array as a string that you can paste into Paste mode.

Empty array. If the input is [], the converter produces an empty NDJSON file (zero lines) and warns that the output contains no lines. This is valid but almost always indicates the wrong file was loaded — check that you are loading the expected export and not an empty placeholder.

JSON parse error. If the input fails to parse, the error panel shows the parser's error message and the approximate position of the problem. Common causes are: trailing commas ({a: 1,}), single-quoted strings ('text'), JavaScript comments (// comment), and unescaped newlines inside string values. Fix the issue in the source file and reload, or edit the pasted text and click Convert again.

Large files. Files above 50 MB are processed in File mode. Paste mode works for large inputs but may be slower due to text area rendering overhead. For very large files (over 100 MB), browser memory limits may cause the tab to slow or crash — in that case, split the file into chunks using a command-line tool before converting.

Unicode and special characters. The converter reads the input as UTF-8 and writes the output as UTF-8. Multi-byte characters — emoji, CJK ideographs, accented characters — pass through unchanged. Strings containing characters that must be escaped in JSON (\n, \t, \\, \") are escaped automatically by JSON.stringify().

Nested objects. If records contain nested objects or arrays, they appear as inline JSON in each NDJSON line. For example, a record {"id": 1, "address": {"city": "Austin", "state": "TX"}} becomes a single NDJSON line: {"id":1,"address":{"city":"Austin","state":"TX"}}. Most NDJSON consumers (Elasticsearch, Spark, DuckDB) handle nested objects natively. If the target system requires a flat schema, flatten the records before converting.

Worked Example

This section shows a complete conversion from start to finish using a small JSON array.

Input JSON (paste this into Paste mode):

[
  {"id": 1, "name": "Alice", "role": "admin", "active": true},
  {"id": 2, "name": "Bob", "role": "editor", "active": true},
  {"id": 3, "name": "Carol", "role": "viewer", "active": false}
]

Steps to follow:

1. Open the JSON to NDJSON Converter.
2. Click the Paste tab.
3. Paste the JSON above into the text area.
4. Click Convert to NDJSON.
5. The stats panel shows: Records: 3, output size approximately 120 bytes, input type: array.
6. The preview panel shows three lines — one per record.
7. Click Download .ndjson. The file is saved as pasted-input.ndjson.

Expected NDJSON output:

{"id":1,"name":"Alice","role":"admin","active":true}
{"id":2,"name":"Bob","role":"editor","active":true}
{"id":3,"name":"Carol","role":"viewer","active":false}

Each record is on its own line, whitespace is removed, and the file ends without a trailing blank line. This file can be loaded directly into Elasticsearch via the Bulk API (with action lines added), ingested by Spark with spark.read.json("pasted-input.ndjson"), or processed with jq as a stream.

For a deeper explanation of what NDJSON is, when to use it, and how the conversion works under the hood, see the Complete Guide to Json To Ndjson.