JSON5

JSON5 is an extension of the JSON format designed to be easier to write and maintain by hand, especially for configuration files. It adds ECMAScript 5.1 conveniences that plain JSON forbids: comments, trailing commas, single-quoted and unquoted object keys, hexadecimal numbers, and multi-line strings, while remaining a strict superset so every valid JSON file is also valid JSON5.

This JavaScript library is the reference implementation of the JSON5 Data Interchange Format, exposing a parse/stringify API that mirrors the native JSON object. It ships with zero runtime dependencies, TypeScript definitions, and a small CLI for converting JSON5 to JSON, and is depended upon by major projects including Chromium, Next.js, and Babel.

What You Get

• A JSON5.parse() function that accepts the full JSON5 grammar plus an optional reviver, matching the native JSON.parse signature.
• A JSON5.stringify() function with replacer, spacing, and custom quote-character options for producing readable output.
• Bundled TypeScript type definitions and both CommonJS and ES module entry points for Node.js and browsers.
• A json5 command-line tool for converting JSON5 files to JSON and validating JSON5 syntax.
• A json5/lib/register hook that lets Node.js require() load .json5 files directly.

Common Use Cases

• Writing application and tooling configuration files that need inline comments and forgiving syntax.
• Loading hand-edited config into a build pipeline or CLI where trailing commas and unquoted keys reduce friction.
• Migrating existing JSON config to a more maintainable format without breaking compatibility.
• Validating or converting JSON5 documents to plain JSON as part of a CI or packaging step.

Under The Hood

Architecture The library is organized as small single-purpose CommonJS modules under lib/, aggregated by lib/index.js into a JSON5 object exposing parse and stringify. lib/parse.js implements a hand-written lexer plus recursive-descent parser driven by two explicit state machines: a lexState table that tokenizes characters into JSON5 tokens and a parseState table that assembles them into a value tree, tracking line, column, and pos so syntax errors report precise locations. lib/stringify.js walks a JavaScript value recursively to emit JSON5 text, honoring replacer functions/arrays, indentation, and a configurable quote character. Character classification (identifier-start, identifier-continue, space separators) is delegated to lib/util.js, which tests against large generated Unicode regexes in lib/unicode.js. lib/cli.js wraps the same API for command-line conversion and validation.

Tech Stack JSON5 is written in plain JavaScript targeting ES5 (engines.node >= 6) with zero runtime dependencies. The distributable bundles are produced by Rollup with the Buble transpiler and Terser minifier (rollup.config.js), generating UMD and ES module builds under dist/. TypeScript consumers are served by hand-authored .d.ts files alongside each module. The lib/unicode.js tables are code-generated via the regenerate and unicode-10.0.0 dev dependencies.

Code Quality The project holds itself to a strict quality bar: the test suite under test/ (parse.js, stringify.js, cli.js, errors.js, require.js) runs under tap with a --100 flag enforcing 100% coverage, and eslint with the standard config runs as part of npm test. Error handling is a strength — the parser throws SyntaxError instances enriched with line and column numbers and descriptive messages. Naming is consistent, modules are cohesive, and TypeScript definitions are maintained in lockstep with the implementation.

API Design The public surface is intentionally tiny and instantly familiar: parse and stringify mirror the native JSON API down to the reviver, replacer, and space parameters, so any JavaScript developer can adopt JSON5 with essentially zero learning curve. The optional object form of stringify (with quote, replacer, and space keys) adds flexibility without complicating the common path, and the README documents every parameter with examples. Node’s require hook and the CLI extend the same mental model to files and the terminal.