# json-beautify

> JSON.stringify for humans

Latest version **2.0.0** (published 2026-08-02) · ISC license · 0 weekly downloads

## Install

```sh
npm install json-beautify
pnpm add json-beautify
yarn add json-beautify
bun add json-beautify
```

Provides the command `json-beautify`.

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-08-02 |
| First published | 2015-05-14 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 38.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 45 |
| Author | Gaëtan Renaudeau |
| Maintainers | gre |
| Keywords | beautifier, beautify, json, prettifier, prettify, pretty, stringify |

## Links

- npm: https://www.npmjs.com/package/json-beautify
- Repository: https://github.com/gre/json-beautify
- Issues: https://github.com/gre/json-beautify/issues
- npm.io page: https://npm.io/package/json-beautify

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 2.0.0 (latest) — 2026-08-02
- 1.1.1 — 2019-09-16
- 1.1.0 — 2019-04-05
- 1.0.1 — 2015-05-14
- 1.0.0 — 2015-05-14

## README

json-beautify: JSON.stringify for humans
========================================

**json-beautify** is a TypeScript implementation of [ECMA-262 §25.5.4](https://tc39.es/ecma262/#sec-json.stringify), the specification of `JSON.stringify`, with one addition: objects and arrays stay on a single line for as long as they fit within a width you choose, and only break when they have to.

For every value, replacer and space it accepts, the positional form produces character-identical output to `JSON.stringify` — boxed primitives, `toJSON`, replacer arrays, `space` clamping, lone-surrogate escaping, `TypeError` on BigInt and on circular structures, and [`JSON.rawJSON`](https://github.com/tc39/proposal-json-parse-with-source) (Node 22+) all behave as the spec requires.

## Install

```sh
npm install json-beautify
```

## Usage

```js
import beautify from "json-beautify";

const obj = {
  str: "Hello World",
  num: 42,
  smallarray: [1, 2, 3, "foo", {}],
  smallobject: { foo: "bar", bar: 42 },
  bigarray: [1, 2, 3, "foo", { foo: "bar", bar: 42, arr: [1, 2, 3, "foo", {}] }],
  bigobject: { foo: [1, 2, 3, "foo", {}], bar: 42, a: { b: { c: 42 } }, foobar: "FooBar" },
};

console.log(beautify(obj, {}));
```

```json
{
  "str": "Hello World",
  "num": 42,
  "smallarray": [ 1, 2, 3, "foo", {} ],
  "smallobject": { "foo": "bar", "bar": 42 },
  "bigarray": [
    1,
    2,
    3,
    "foo",
    { "foo": "bar", "bar": 42, "arr": [ 1, 2, 3, "foo", {} ] }
  ],
  "bigobject": {
    "foo": [ 1, 2, 3, "foo", {} ],
    "bar": 42,
    "a": { "b": { "c": 42 } },
    "foobar": "FooBar"
  }
}
```

Widen it and more stays inline:

```js
console.log(beautify(obj, { maxWidth: 100 }));
```

```json
{
  "str": "Hello World",
  "num": 42,
  "smallarray": [ 1, 2, 3, "foo", {} ],
  "smallobject": { "foo": "bar", "bar": 42 },
  "bigarray": [ 1, 2, 3, "foo", { "foo": "bar", "bar": 42, "arr": [ 1, 2, 3, "foo", {} ] } ],
  "bigobject": {
    "foo": [ 1, 2, 3, "foo", {} ],
    "bar": 42,
    "a": { "b": { "c": 42 } },
    "foobar": "FooBar"
  }
}
```

## Options

| Option | Type | Default | |
| --- | --- | --- | --- |
| `replacer` | function \| array \| null | `null` | §25.5.4 `replacer`: a filter function, or an array of keys to keep. |
| `space` | number \| string | `2` | §25.5.4 `space`: indent width, or the literal indent string. |
| `maxWidth` | number | `80` | Maximum line width. `0` always breaks, `Infinity` never does. |
| `sortKeys` | boolean \| comparator | `false` | Sort object keys instead of using their natural order. |
| `arrayPadding` | string | `" "` | Padding inside a single-line array. `""` gives `[1, 2]`. |
| `objectPadding` | string | `" "` | Padding inside a single-line object. `""` gives `{"a": 1}`. |

An unknown option name throws, so a typo like `maxwidth` is caught rather than silently ignored.

### `sortKeys`

```js
console.log(beautify({ z: 1, a: { d: 1, b: 2 } }, { sortKeys: true }));
// { "a": { "b": 2, "d": 1 }, "z": 1 }
```

Pass a comparator for a custom order:

```js
beautify(value, { sortKeys: (a, b) => a.length - b.length });
```

A `replacer` array is itself an explicit ordering, so `sortKeys` leaves it alone.

### Padding

```js
beautify({ a: [1, 2] }, {});                                  // { "a": [ 1, 2 ] }
beautify({ a: [1, 2] }, { arrayPadding: "" });                 // { "a": [1, 2] }
beautify({ a: [1, 2] }, { arrayPadding: "", objectPadding: "" }); // {"a": [1, 2]}
```

### `maxWidth` is a bound, not an estimate

The width accounts for the indent, the `"key": ` prefix the value sits behind, and the comma that follows it. No line exceeds `maxWidth` unless it holds a single value too long to break — a long string, or a key wider than the budget.

## `JSON.stringify` compatibility

The positional signature is still supported, and is a drop-in replacement:

```js
beautify(value, replacer, space, maxWidth);
```

Called this way, `space` and `maxWidth` default to off rather than to `2` and `80`, so `beautify(value, replacer, space)` is exactly `JSON.stringify(value, replacer, space)`. The options form is the front door and defaults to readable output; the positional form is the compatibility path.

It is stricter than `JSON.stringify` about arguments: a malformed replacer, width or option name throws instead of being silently ignored. This affects argument validation only, never how an accepted value is serialized.

## CLI

```sh
npx json-beautify [options] <file...>
```

Rewrites each file in place.

```
-w, --width <n>       maximum line width (default 80)
-i, --indent <n|str>  indent width, or the literal indent string (default 2)
-s, --sort-keys       sort object keys
-c, --compact         no padding inside single-line arrays and objects
-h, --help            show this message
```

## Development

```sh
npm install
npm run build      # compile TypeScript to dist/
npm test           # compile + run the test suite (node:test)
npm run typecheck  # type-check only, no emit
npm run lint       # oxlint
npm run fmt        # oxfmt (use fmt:check in CI)
```

---
_Source: https://npm.io/package/json-beautify · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._