# Add Compression to a Koa App

Yes. An agent adds koa-compress to your Koa API with a threshold and encodings that fit its Node version, tests gzip and brotli responses over HTTP, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-compression/koa/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the middleware chain before it adds a link to it. In an API laid out like javieraviles/node-typescript-koa-rest, `src/server.ts` opens a TypeORM connection and then builds the app in order: `koa-helmet`'s `contentSecurityPolicy`, `@koa/cors` with defaults, the winston `logger` from `src/logger.ts` that times each request and logs `method url status ms`, `koa-bodyparser`, the `unprotectedRouter` (`GET /` answering `Hello World!`), `koa-jwt` with `.unless({ path: [/^\/swagger-/] })`, and the `protectedRouter`, a `SwaggerRouter` from `koa-swagger-decorator` that serves the user routes, `/swagger-json` and `/swagger-html`. `package.json` runs `koa ^2.13.1` with `engines` at Node `14.x.x` and npm `6.x.x`, the `Dockerfile` builds on `node:14-alpine`, and `tsconfig.json` targets ES2017 with `lib: ["es6"]` and `noImplicitAny`. The `lint` script is `tsc --noEmit` plus ESLint, `test` is Jest 26 through `ts-jest`, and the two test files under `tests/` mock `typeorm` and `class-validator` and never start the server.

The agent installs `koa-compress` and, when `tsc --noEmit` asks for them, its type declarations, and adds `src/compression.ts` exporting a configured middleware: `threshold: 1024`, so the twelve-byte hello-world text and a single user object stay as they are; `br` left at the package's default quality of 4 because Node 14 has Brotli in `zlib`; `gzip` and `deflate` as fallbacks; and the default `filter`, the `compressible` list, which covers `application/json` and `text/html`. `zstd` needs nothing: `koa-compress` enables it only when `zlib.createZstdCompress` exists, which Node 14 lacks and a later Node provides. In `server.ts` the middleware goes right after `cors()` and before the logger, so every router response, the JSON user list and the swagger page, passes through it, and the timing the logger writes includes the compression.

Two responses are handled on purpose. `/swagger-html` is the largest page the app serves and is the one a reviewer will see change in the network panel, so the pull request measures it; and the error path in `src/logger.ts`, which sets `ctx.body = err.message` on a thrown error, stays uncompressed under the threshold, so a `401` from `koa-jwt` reads the same as before. The agent leaves `ctx.compress` alone in the controllers: the README's `DELETE /testusers` and the user routes return small bodies, and forcing compression on them would cost CPU for nothing.

Because the existing tests never open a socket, the agent writes `tests/compression.test.ts` with Node's own `http` and `zlib`: it builds a small `Koa` app with the exported middleware and a route that answers a JSON body larger than the threshold, listens on port 0, requests it with `Accept-Encoding: gzip` and checks `content-encoding: gzip` and that `gunzipSync` of the bytes parses to the original; repeats with `br` and `brotliDecompressSync`; requests a body the size of the hello-world text and asserts no `content-encoding`; and requests with no `Accept-Encoding` and asserts identity, which is the package's `defaultEncoding`. The test uses no new dependency and runs under `ts-jest` with the `testMatch` already in `package.json`. The agent runs `npm ci`, `npm run lint` and `npm test` in its sandbox, then starts the server against a Postgres it runs there, as `docker-compose.yml` does with `postgres:10-alpine`, and records the `content-length` of `/swagger-html` with and without `Accept-Encoding: br`.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add response compression to this Koa and TypeScript API. Read package.json, tsconfig.json, src/server.ts, src/logger.ts, src/config.ts, src/unprotectedRoutes.ts, src/protectedRoutes.ts, src/controller/user.ts, the Dockerfile and the tests under tests first. Install koa-compress and any type declarations tsc --noEmit needs. Add src/compression.ts exporting the middleware with a 1024-byte threshold, brotli at the default quality, gzip and deflate, and use it in server.ts after cors and before the logger. Write tests/compression.test.ts with node's http and zlib that start a small Koa app with the middleware and assert gzip and br responses decompress to the body, that a body under the threshold is not encoded, and that a request without Accept-Encoding gets identity. Run npm ci, npm run lint and npm test, then start the server against a Postgres in the sandbox and record the size of /swagger-html with and without Accept-Encoding: br. Quote the output. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `src/compression.ts` and `tests/compression.test.ts`, changes `src/server.ts` (one `app.use`), `package.json` and `package-lock.json` (the dependency), and the README's included-middleware list. Its description quotes `npm run lint` and `npm test`, and shows the two `content-length` values for `/swagger-html`, plain and brotli, from the agent's own server.

A reviewer starts the server, opens `/swagger-html` with the network panel and reads the `content-encoding` header, then requests `/` and sees none. In the code they check the middleware's position, that nothing above it in `server.ts` writes a body, and that the threshold matches what they want: a lower one compresses the single-user responses, which the pull request leaves as a one-number change.

No route, controller or entity changes. The Postman collection under `integrationtests/` and the `newman` scripts keep working, since `newman` decompresses what it is sent.

## Run it on every new Node service

A platform team that wants every HTTP service to compress its responses starts this from its own server: a handler lists the repositories and, for each one whose `package.json` has `koa`, `express` or `fastify` and no compression package, sends this body to `POST /o/{org}/sessions` with that repository in `resources`. A `request_id` that is a UUID v5 of the repository's full name keeps a retried call from starting a second run, since the same `request_id` and body return the run already started.

A Rush automation with a `github` trigger on `pull_request.opened` can watch for a new route whose response would be large; its runs are read-only, so they comment and do not push. The run that adds the middleware is the one above.

## Why run it on Rush?

Compression is a header you have to see to believe. The agent runs the server in its own sandbox with a database beside it, requests the swagger page with and without `Accept-Encoding`, and keeps the two sizes and the test output with the pull request, so the reviewer compares numbers the agent measured rather than a claim that the middleware is on.

A team with several Node services on different frameworks starts the same request for each at once. Each run reads its own middleware chain, Node version and routes, so a Node 14 service gets Brotli and gzip and a Node 22 service also gets zstd, and each pull request says which.

## Frequently asked questions

### Where does the middleware go in server.ts?

After `cors()` and before the winston logger, so the two routers and the swagger pages are all downstream of it. Koa middleware wraps what comes after it, and a compressor placed after a router would never see that router's body.

### Does Brotli work on Node 14?

Yes. `zlib` has had Brotli since Node 11.7, and `koa-compress` uses it at its default quality of 4. `zstd` is different: the package turns it on only when `zlib.createZstdCompress` exists, which arrives in Node 22.15, so on this `engines` setting it stays off without any configuration.

### Why a 1024-byte threshold?

It is the package default and it keeps the small bodies this API returns, the hello-world text, one user, a `401` message, out of the compressor, where the CPU cost would exceed the bytes saved. The user list and the swagger page are over it. The number is one line in `src/compression.ts`.

### Why not use supertest for the test?

The repository has no HTTP test dependency, and Node's `http` and `zlib` are enough to request a listening app and decompress what it returns. Adding `supertest` would be a reasonable choice too; the pull request says so and keeps the dependency list as it is.

## More Koa jobs

- [Add CORS to a Koa App](https://getrush.ai/run/add-cors/koa/)
- [Add Test Coverage to CI for a Koa API](https://getrush.ai/run/add-coverage-to-ci/koa/)
- [Add TypeORM Migrations to a Koa API](https://getrush.ai/run/add-database-migrations/koa/)

## The same job on other stacks

- [Add Response Compression to a Ktor API](https://getrush.ai/run/add-compression/ktor/)
- [Add Response Compression to a Leptos Axum App](https://getrush.ai/run/add-compression/leptos/)
- [Add Response Compression to a Litestar App](https://getrush.ai/run/add-compression/litestar/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
