koa-json

library2.0.2jsnpmunverified

koa-json is a Koa middleware designed to pretty-print JSON responses and convert Node.js object streams into binary output. While the package itself, currently at version `2.0.2`, was last updated in April 2016, it remains functional and compatible with recent Koa versions (2.x and 3.x) which utilize async/await middleware. It serves a specific utility by automatically formatting `ctx.body` objects into human-readable, indented JSON, offering options to control pretty-printing behavior via a query string parameter or global configuration. This differentiates it from `koa-bodyparser`, which handles parsing incoming JSON requests. Due to its long-standing stability and the specialized nature of its function, the project's release cadence is effectively dormant, but it continues to be a viable option for adding structured JSON output to Koa applications.

web-framework serialization

npm install koa-json

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-JSON

koa-json

web-frameworkjavascriptv2.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

json

✓ import json from 'koa-json';

✗ import { json } from 'koa-json';

The package exports a default function. Use `import json from 'koa-json'` in ESM, or `import * as json from 'koa-json'` if default import interop is not configured. TypeScript users typically import this way.

json (CommonJS)

✓ const json = require('koa-json');

✗ import json from 'koa-json';

This is the standard CommonJS import pattern as shown in the original documentation.

Middleware setup

✓ app.use(json({ pretty: true, spaces: 2 }));

✗ app.use(json);

The imported `json` function must be called to return the actual middleware, optionally with configuration options.

This quickstart initializes a Koa application and applies `koa-json` middleware to automatically pretty-print all JSON responses. It demonstrates setting a simple object on `ctx.body` which `koa-json` then formats, also showing how to enable pretty-printing via a query parameter.

import Koa from 'koa'; import json from 'koa-json'; const app = new Koa(); // Apply the koa-json middleware. By default, it pretty-prints responses. // You can disable pretty printing by default and enable via a query parameter. app.use(json({ pretty: true, param: 'pretty' })); // Define a route that sets a JSON object on ctx.body app.use(async (ctx) => { ctx.body = { message: 'Hello, Koa!', data: { timestamp: new Date().toISOString(), version: '1.0.0' } }; }); const PORT = process.env.PORT ?? 3000; app.listen(PORT, () => { console.log(`Koa server running on http://localhost:${PORT}`); console.log('Try accessing / to see pretty JSON.'); console.log('Or /?pretty to enable pretty printing if default is false.'); });

Debug

Known issues

gotchaThe `koa-json` package has not been updated since April 2016. While it remains compatible with modern Koa versions (2.x and 3.x), it means no new features or direct compatibility fixes for very recent Node.js changes will be provided. The core functionality, however, is stable.

fix

Ensure thorough testing with your specific Koa and Node.js versions. Consider alternative, more actively maintained JSON middleware if advanced features or stricter compatibility guarantees are required, although this package serves its basic purpose reliably.

affects: >=2.0.0

gotchaConfusion with `koa-bodyparser`: `koa-json` is solely for pretty-printing *outgoing* JSON responses. It does not parse *incoming* JSON request bodies. Using `ctx.request.body` will be `undefined` if you expect it to parse incoming JSON without `koa-bodyparser` or similar middleware.

fix

For parsing incoming JSON request bodies, install and use `@koa/bodyparser` (or `koa-bodyparser`) middleware alongside `koa-json`. Example: `app.use(bodyParser()); app.use(json());`

affects: *

gotchaThe `param` option in `koa-json` can unintentionally expose pretty-printed JSON in production environments if not carefully managed. If `pretty: false` is the default, but `param: 'pretty'` is set, appending `?pretty` to any URL will force pretty-printed output, which might expose internal data structures or increase response size.

fix

In production, either set `pretty: false` and omit the `param` option entirely, or ensure that the `param` value is sufficiently obscure or protected by authentication if pretty-printing is required for specific debugging scenarios.

affects: *

Errors

Common errors & fixes

Error: `obj` must be an object (koa-json internal error or similar)

`koa-json` received `ctx.body` that was not an object, array, or stream that could be serialized into JSON.

fix

Ensure `ctx.body` is set to a valid JavaScript object, array, or a Node.js object stream before `koa-json` middleware processes the response. `koa-json` expects a serializable structure.

TypeError: Converting circular structure to JSON

Attempting to serialize a JavaScript object with circular references within `ctx.body`.

fix

Before `koa-json` processes the response, ensure that any objects assigned to `ctx.body` do not contain circular references. Manually serialize complex objects or use a library to handle circular references if necessary, or filter out problematic properties.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

koarequiredkoa-json is a middleware designed for the Koa web framework; Koa is required to use it.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/koajs/json ↗

packagehttps://www.npmjs.com/package/koa-json ↗