{"id":17135,"library":"koa-json","title":"Koa JSON Response Pretty-Printer","description":"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.","status":"maintenance","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/koajs/json","tags":["javascript","koa","json"],"install":[{"cmd":"npm install koa-json","lang":"bash","label":"npm"},{"cmd":"yarn add koa-json","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-json","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"koa-json is a middleware designed for the Koa web framework; Koa is required to use it.","package":"koa","optional":false}],"imports":[{"note":"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.","wrong":"import { json } from 'koa-json';","symbol":"json","correct":"import json from 'koa-json';"},{"note":"This is the standard CommonJS import pattern as shown in the original documentation.","wrong":"import json from 'koa-json';","symbol":"json (CommonJS)","correct":"const json = require('koa-json');"},{"note":"The imported `json` function must be called to return the actual middleware, optionally with configuration options.","wrong":"app.use(json);","symbol":"Middleware setup","correct":"app.use(json({ pretty: true, spaces: 2 }));"}],"quickstart":{"code":"import Koa from 'koa';\nimport json from 'koa-json';\n\nconst app = new Koa();\n\n// Apply the koa-json middleware. By default, it pretty-prints responses.\n// You can disable pretty printing by default and enable via a query parameter.\napp.use(json({ pretty: true, param: 'pretty' }));\n\n// Define a route that sets a JSON object on ctx.body\napp.use(async (ctx) => {\n  ctx.body = {\n    message: 'Hello, Koa!',\n    data: {\n      timestamp: new Date().toISOString(),\n      version: '1.0.0'\n    }\n  };\n});\n\nconst PORT = process.env.PORT ?? 3000;\napp.listen(PORT, () => {\n  console.log(`Koa server running on http://localhost:${PORT}`);\n  console.log('Try accessing / to see pretty JSON.');\n  console.log('Or /?pretty to enable pretty printing if default is false.');\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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());`","message":"Confusion 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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"`koa-json` received `ctx.body` that was not an object, array, or stream that could be serialized into JSON.","error":"Error: `obj` must be an object (koa-json internal error or similar)"},{"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.","cause":"Attempting to serialize a JavaScript object with circular references within `ctx.body`.","error":"TypeError: Converting circular structure to JSON"}],"ecosystem":"npm","meta_description":null}