How to Parse a JSON File in JavaScript
JSON is a text format, so JavaScript cannot use a file's contents as data until something reads that text and converts it into a value.
The conversion step is JSON.parse(). Everything else is about getting the text in the first place: from disk in Node.js, over HTTP in a browser, or through a module import. This guide walks through each route with runnable examples, then separates the two failure points you will meet — a file that cannot be read, and a file whose text is not valid JSON.
The two-step model: read, then parse
:The core pattern never changes. First obtain the file contents as a string. Then hand that string to JSON.parse(), which returns a JavaScript value such as an object or array. In Node.js the reading step comes from the built-in node:fs module. In a browser the reading step usually comes from fetch(), and response.json() performs the parse for you.
Reading a JSON file in Node.js asynchronously
fs.readFile() reads from disk without holding up the rest of the Node.js process while the operation completes. The example below reads data.json as UTF-8 text, then parses it. The sample file used throughout is a small object with a name, an age, and a nested address.
Reading a JSON file in Node.js synchronously
fs.readFileSync() returns the file contents directly and blocks execution until the read finishes. That is acceptable in small scripts or in startup and configuration code, but asynchronous reading is generally the better choice when blocking the process would be undesirable. The synchronous version below wraps both the read and the parse in a single try/catch.
Reading JSON in the browser with fetch
Browser JavaScript cannot open arbitrary local files on its own. When JSON is served by a web server, fetch() retrieves it and response.json() reads the response body and parses it as JSON. The example uses three files — index.js, data.json, and index.html — served locally with http-server on port 8000. Open the browser developer tools and check the Console tab for the parsed object.
Importing a JSON file in Node.js
CommonJS can load a local JSON file directly with require(), and the result is already the parsed contents. ECMAScript modules need a JSON import attribute: the with { type: 'json' } clause tells Node.js that the imported file contains JSON. Save the module with an .mjs extension, for example index.mjs, and run it with node index.mjs. Alternatively, add "type": "module" to package.json so .js files are treated as ES modules.
Parsing a JSON file that contains an array
A JSON file can hold a top-level array rather than an object. JSON.parse() handles it the same way; the difference is that the returned value is an array, so you can iterate over it. The example below reads an array of people and prints each person's name and age.
Choosing a read method
Use this comparison to pick the route that fits your environment and your tolerance for blocking.
Read failure versus parse failure
Reading and parsing are separate operations, and they fail for different reasons. fs.readFile() can fail when the file cannot be read — a missing path, a permission problem, or an I/O error. JSON.parse() throws a SyntaxError when the text it receives is not valid JSON. In the asynchronous example, the read error is handled in the callback's error branch and the parse error is caught in a try/catch around JSON.parse(), so each failure produces its own message. Keep those two handlers distinct when you adapt the code.
Checklist before you run the examples
- Confirm the file path is correct relative to the script that runs it.
- Pass 'utf8' as the encoding so you receive a string rather than a buffer.
- Wrap JSON.parse() in try/catch so invalid JSON produces a readable message.
- In the browser, serve the files over HTTP before calling fetch(); opening index.html directly from disk will not work.
- For ES module imports, include the with { type: 'json' } attribute and use an .mjs file or set "type": "module" in package.json.
- If the file holds an array, iterate the parsed result rather than assuming an object.
| Environment | Read step | Parse step | Blocking behavior |
|---|---|---|---|
| Node.js (async) | fs.readFile('data.json', 'utf8', callback) | JSON.parse(jsonText) inside try/catch | Does not block the process while reading |
| Node.js (sync) | fs.readFileSync('data.json', 'utf8') | JSON.parse(jsonText) inside try/catch | Blocks until the file is read |
| Browser over HTTP | fetch('./data.json') | response.json() | Asynchronous |
| Node.js CommonJS | require('./data.json') | Handled by require() | Loads the parsed contents directly |
| Node.js ES modules | import data from './data.json' with { type: 'json' } | Handled by the import | Requires the JSON import attribute |
The browser route requires the files to be served by a web server; browser JavaScript cannot read arbitrary local files directly.
Frequently asked questions
Why does JSON.parse() throw a SyntaxError?
JSON.parse() only accepts valid JSON text. If the file contains a trailing comma, single quotes, comments, or another non-JSON construct, parsing fails with a SyntaxError. The read itself can still succeed, which is why the parse call belongs in its own try/catch.
Should I use fs.readFile() or fs.readFileSync()?
Use fs.readFile() when you do not want the file operation to block the rest of the Node.js process. fs.readFileSync() blocks until the read completes and is reasonable for small scripts or startup and configuration code.
Can I fetch a local JSON file in the browser without a server?
No. Browser JavaScript cannot directly read arbitrary local files. Serve the JSON through a web server — the example uses http-server on port 8000 — and then fetch it over HTTP.
Why does an ES module import of JSON need an import attribute?
Current Node.js requires the with { type: 'json' } attribute on a JSON import so it knows the imported file contains JSON. Use an .mjs file, or set "type": "module" in package.json, to run the module.
{
"name": "John Doe",
"age": 32,
"address": {
"street": "123 Main St",
"city": "Anytown",
"state": "CA"
}
}
{
"name": "John Doe",
"age": 32,
"address": {
"street": "123 Main St",
"city": "Anytown",
"state": "CA"
}
}
{
"type": "module"
}
[
{ "name": "John Doe", "age": 32 },
{ "name": "Joe Doe", "age": 30 },
{ "name": "Alice", "age": 28 }
]