Learn JSON5

Step-by-step tutorials to get you up and running in minutes.

Getting Started Syntax Node.js Browser Converting Quick Reference

Getting Started

JSON5 is a superset of JSON that adds human-friendly features. Here's what you need to know to start using it.

1

Understand what JSON5 is

JSON5 extends JSON with features borrowed from ECMAScript 5.1. It's designed for configuration files and other human-edited data.

Key insight: Every JSON file is already valid JSON5. You can adopt features gradually.

2

Install the JSON5 library

To parse JSON5 in your code, you need the json5 package. Install it via npm:

npm install json5
3

Create your first JSON5 file

Create a file named config.json5 with human-friendly features:

{ // App configuration name: 'my-app', version: '1.0.0', debug: true, // Enable for development }
4

Parse it in your code

Use the JSON5 library to read your config file:

import JSON5 from 'json5'; import { readFileSync } from 'fs'; const configText = readFileSync('config.json5', 'utf8'); const config = JSON5.parse(configText); console.log(config.name); // 'my-app'

Syntax Fundamentals

Master the core JSON5 syntax features that make configuration files more readable.

Comments

Add explanations with // or /* */

// Single-line comment /* Multi-line comment */

Trailing Commas

Safe to leave commas after the last item

{ a: 1, b: 2, } // OK! [ 1, 2, 3, ] // OK!

Unquoted Keys

Skip quotes on valid identifiers

{ name: 'value' } // Instead of {"name": "value"}

Single Quotes

Use single or double quotes for strings

{ msg: 'Hello "World"' } // No escaping needed

Extended Numbers

Hex, Infinity, NaN, and flexible decimals

{ hex: 0xFF, inf: Infinity, half: .5 }

Multi-line Strings

Continue strings across lines with backslash

{ text: 'Line 1 \ Line 2' }

Using JSON5 in Node.js

Complete guide to integrating JSON5 in your Node.js applications.

Installation

npm install json5

Basic Usage (ES Modules)

import JSON5 from 'json5'; // Parse JSON5 string const obj = JSON5.parse(`{ name: 'app', // comment version: '1.0', }`); // Stringify to JSON5 const str = JSON5.stringify(obj, null, 2);

CommonJS Syntax

const JSON5 = require('json5'); const config = JSON5.parse(configString);

Reading JSON5 Files

import JSON5 from 'json5'; import { readFileSync } from 'fs'; function loadConfig(path) { const content = readFileSync(path, 'utf8'); return JSON5.parse(content); } const config = loadConfig('./config.json5'); console.log(config);

With TypeScript

import JSON5 from 'json5'; interface AppConfig { name: string; version: string; debug: boolean; } const config = JSON5.parse<AppConfig>(configString);

The json5 package includes TypeScript definitions.

Using JSON5 in Browsers

Load and parse JSON5 files directly in web applications.

Via CDN (Quick Start)

<script src="https://unpkg.com/json5@2/dist/index.min.js"></script> <script> const config = JSON5.parse(`{ theme: 'dark', sidebar: true, // Show sidebar }`); console.log(config.theme); // 'dark' </script>

With a Bundler (Vite, Webpack, etc.)

// Install first: npm install json5 import JSON5 from 'json5'; // Fetch and parse JSON5 async function loadConfig() { const response = await fetch('/config.json5'); const text = await response.text(); return JSON5.parse(text); } loadConfig().then(config => { console.log(config); });

ES Module Import

<script type="module"> import JSON5 from 'https://unpkg.com/json5@2/dist/index.min.mjs'; const config = JSON5.parse(`{ debug: true }`); </script>

Converting JSON to JSON5

Migrate your existing JSON files to JSON5 format.

Good news: Your JSON files are already valid JSON5! You can rename them to .json5 and start adding features gradually.

Before & After Example

package.json (Original)

{ "name": "my-app", "version": "1.0.0", "scripts": { "start": "node index.js", "test": "jest" } }

package.json5 (Enhanced)

{ name: 'my-app', version: '1.0.0', scripts: { // Start the development server start: 'node index.js', // Run test suite test: 'jest', }, }

Conversion Checklist

Quick Reference Card

Print this or keep it handy for fast lookups.

Objects

{ unquoted: 'key', 'quoted': 'key', trailing: 'comma', }

Arrays

[ 1, 2, 3, // trailing OK ]

Strings

"double quotes" 'single quotes' 'multi \ line'

Numbers

42 // integer 0xFF // hex .5 // leading decimal Infinity // special

Comments

// single line /* multi line */

Special Values

true false null Infinity NaN
Download PDF Cheat Sheet

Ready to Practice?

Check out real-world examples or explore the complete syntax comparison.

See Examples JSON vs JSON5