JSON File Handling

A JSON file is a plain text file with a .json extension. It stores data in JSON format so applications can read it, save to it, and share it. JSON files are used for configuration, data storage, API mocking, and transferring data between systems.

What is a JSON File

Imagine a filing cabinet in an office. Each drawer holds a set of organized papers. A JSON file is like one of those drawers — it holds structured data in a format that both humans and computers can read. Unlike a database, a JSON file needs no server. It sits on your hard drive and works with any text editor.

A Simple JSON File (users.json)

[
  {
    "id": 1,
    "name": "Ankita Rao",
    "email": "ankita@example.com"
  },
  {
    "id": 2,
    "name": "Dev Kumar",
    "email": "dev@example.com"
  }
]

Save this text in a file named users.json. Any application can now read this file and work with the data inside.

JSON File Naming Rules

• Use the .json extension.
• Use lowercase letters and hyphens: user-profile.json, product-list.json.
• Avoid spaces in file names.
• Use descriptive names that reflect the content: config.json, orders.json.

Reading a JSON File in JavaScript (Node.js)

Node.js provides two main ways to read a JSON file: using require() for simple cases and using the fs module for more control.

Method 1: Using require() — Simple and Fast

// Node.js reads and parses the file automatically
const users = require('./users.json');

console.log(users[0].name); // Ankita Rao

The require() method reads the file, parses the JSON, and returns a JavaScript object. This method is synchronous and works well for configuration files that load once at startup.

Method 2: Using the fs Module — More Control

const fs = require('fs');

// Asynchronous reading (does not block other code)
fs.readFile('./users.json', 'utf8', (err, data) => {
  if (err) {
    console.error('Error reading file:', err);
    return;
  }
  const users = JSON.parse(data);
  console.log(users);
});

The fs.readFile() method reads the file in the background. When the file is ready, it calls the function with the content. You then use JSON.parse() to convert the string into a usable object.

Method 3: Using fs.promises (Modern Async/Await)

const fs = require('fs').promises;

async function loadUsers() {
  const data = await fs.readFile('./users.json', 'utf8');
  const users = JSON.parse(data);
  return users;
}

loadUsers().then(users => console.log(users));

Writing a JSON File in Node.js

Writing to a JSON file means converting your JavaScript object to a string with JSON.stringify() and then saving it.

Writing Data to a JSON File

const fs = require('fs');

const newUser = { id: 3, name: "Sara Joshi", email: "sara@example.com" };

// Convert object to formatted JSON string
const jsonString = JSON.stringify(newUser, null, 2);

fs.writeFile('./new-user.json', jsonString, 'utf8', (err) => {
  if (err) {
    console.error('Error writing file:', err);
    return;
  }
  console.log('File saved successfully!');
});

The second argument null and third argument 2 in JSON.stringify() add two-space indentation. This makes the output file readable.

Diagram: Read and Write Flow

READING A JSON FILE
--------------------
users.json (disk)
    |
    v
fs.readFile() reads raw text
    |
    v
JSON.parse() converts text to object
    |
    v
JavaScript object ready to use

WRITING A JSON FILE
--------------------
JavaScript object
    |
    v
JSON.stringify() converts object to text
    |
    v
fs.writeFile() saves text to disk
    |
    v
users.json updated on disk

Reading and Writing JSON Files in Python

Python makes JSON file handling very clean with the built-in json module.

Reading a JSON File in Python

import json

with open('users.json', 'r', encoding='utf-8') as file:
    users = json.load(file)

print(users[0]['name'])  # Ankita Rao

The json.load() function reads the file and parses it in one step. The with statement automatically closes the file after reading.

Writing a JSON File in Python

import json

new_user = {"id": 3, "name": "Sara Joshi", "email": "sara@example.com"}

with open('new-user.json', 'w', encoding='utf-8') as file:
    json.dump(new_user, file, indent=2)

print("File saved!")

The json.dump() function converts the Python dictionary to JSON and writes it directly to the file. The indent=2 argument formats the output with two spaces.

Reading and Writing JSON Files in PHP

Reading a JSON File in PHP

<?php
$content = file_get_contents('users.json');
$users = json_decode($content, true);

echo $users[0]['name']; // Ankita Rao
?>

Writing a JSON File in PHP

<?php
$newUser = ["id" => 3, "name" => "Sara Joshi", "email" => "sara@example.com"];
$jsonString = json_encode($newUser, JSON_PRETTY_PRINT);
file_put_contents('new-user.json', $jsonString);
echo "File saved!";
?>

Real-World Use Case: Config File

Many applications use a config.json file to store settings. Instead of hardcoding values inside the code, you place them in the JSON file. When you need to change a setting, you edit the file — not the code.

config.json

{
  "appName": "MyShop",
  "version": "2.1.0",
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myshop_db"
  },
  "currency": "INR",
  "maxCartItems": 10
}

Reading the Config in Node.js

const config = require('./config.json');

console.log(config.appName);         // MyShop
console.log(config.database.port);   // 5432

Updating a JSON File (Read → Modify → Write)

The standard pattern for modifying a JSON file is: read the file, change the data in memory, write it back.

const fs = require('fs');

// Step 1: Read
const data = fs.readFileSync('./users.json', 'utf8');
const users = JSON.parse(data);

// Step 2: Modify
users.push({ id: 3, name: "Sara Joshi", email: "sara@example.com" });

// Step 3: Write back
fs.writeFileSync('./users.json', JSON.stringify(users, null, 2), 'utf8');

console.log("User added!");

Common Errors When Handling JSON Files

Error 1: File Not Found

Happens when the file path is wrong. Check if the file name and directory path are correct.

Error 2: Invalid JSON in File

Happens when the file contains invalid JSON. Use a JSON validator tool to find syntax errors before reading the file in code.

Error 3: Encoding Issues

Always specify utf-8 encoding when reading or writing files to avoid garbled characters in names and text.

Error 4: Race Conditions in Async Code

When multiple parts of your code read and write the same JSON file at the same time, data can get corrupted. Use locks or a proper database for concurrent writes.

JSON Files vs Databases

JSON File                   Database
---------                   --------
Good for small data         Good for large data
No setup needed             Requires installation
No concurrent writes        Supports concurrent writes
Human-readable              Optimized for speed
Good for config/mock data   Good for production apps

Summary

JSON files store structured data in plain text. You read them by parsing the text into objects and write them by converting objects back to text. Node.js, Python, and PHP all have built-in tools for JSON file handling. Use JSON files for configuration, small data sets, and API mocking. For large-scale or concurrent data needs, use a proper database instead.