koa-override

library4.0.0jsnpmunverified

koa-override is a Koa middleware designed to enable clients to utilize HTTP verbs like PUT or DELETE in environments where direct support is limited, typically by overriding the method via a `_method` field in the request body or an `X-HTTP-Method-Override` header. The current stable version is 4.0.0, released in June 2024. This package is maintained by the Egg.js team, indicating active development and stability within the Koa ecosystem. It provides a simple API, `override([options])`, allowing configuration of allowed override methods (defaulting to `POST` requests). A key differentiator is its explicit method overriding mechanism, making it a robust solution for RESTful API compatibility challenges with legacy clients or specific network constraints. It ships with TypeScript types and supports both CommonJS and ES Modules since version 4.0.0.

web-framework http-networking

npm install koa-override

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-OVERRIDE

koa-override

web-frameworkjavascriptv4.0.0

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.

override

✓ import override from 'koa-override';

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

The default export is the middleware factory function. Since v4.0.0, it supports both ESM and CJS.

override (CommonJS)

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

CommonJS syntax for Node.js environments. Works since v4.0.0 supports both CJS/ESM.

Middleware usage

✓ app.use(override());

✗ app.use(override);

`override` is a factory function that returns the actual middleware. It must be called, even with no options.

Demonstrates setting up a basic Koa application with `koa-override` and `koa-bodyparser` to allow method overriding via request body (`_method`) or HTTP header (`X-HTTP-Method-Override`).

import Koa from 'koa'; import bodyParser from 'koa-bodyparser'; import override from 'koa-override'; const app = new Koa(); // Add a body parser to handle _method in the request body app.use(bodyParser()); // Apply the method override middleware // By default, it checks `body._method` then `X-HTTP-Method-Override` header // Overrides are only allowed on POST requests by default. app.use(override()); app.use(async (ctx, next) => { if (ctx.method === 'DELETE') { ctx.body = `Received a simulated DELETE request for ${ctx.url}`; } else if (ctx.method === 'PUT') { ctx.body = `Received a simulated PUT request for ${ctx.url} with body: ${JSON.stringify(ctx.request.body)}`; } else { await next(); } }); app.use(async (ctx) => { ctx.body = `Received original ${ctx.method} request for ${ctx.url}`; }); const port = 3000; app.listen(port, () => { console.log(`Server listening on http://localhost:${port}`); console.log('Try POSTing to /test with X-HTTP-Method-Override: PUT, or with body: { "_method": "DELETE" }'); });

Debug

Known issues

breakingVersion 4.0.0 drops support for Node.js versions older than 18.19.0. Projects on older Node.js versions must upgrade Node.js or remain on `koa-override` v3.

fix

Upgrade Node.js to version 18.19.0 or higher, or explicitly install `koa-override@3`.

affects: >=4.0.0

gotchaTo override methods using the `_method` field in the request body (e.g., from an HTML form), a body parsing middleware like `koa-bodyparser` is required to parse the request body before `koa-override` can access it.

fix

Ensure `koa-bodyparser` or a similar body parser middleware is used *before* `koa-override` in your middleware chain: `app.use(bodyParser()); app.use(override());`

affects: >=1.0.0

gotchaBy default, `koa-override` only allows method overriding on `POST` requests. Attempts to override methods on `GET` or other request types will be ignored unless `options.allowedMethods` is configured.

fix

If you need to override methods on non-POST requests, configure `koa-override` with `app.use(override({ allowedMethods: ['POST', 'GET', 'PATCH'] }));`

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: override is not a function

The `override` import refers to the middleware factory, which must be called to produce the actual middleware.

fix

Change `app.use(override)` to `app.use(override())`.

Method override not working when using _method in form data

The request body, containing `_method`, has not been parsed yet when `koa-override` attempts to read it.

fix

Add a body parser middleware, like `koa-bodyparser`, before `koa-override`. Example: `app.use(bodyParser()); app.use(override());`

Method override not working for GET requests or other non-POST methods

By default, `koa-override` only applies method overriding to `POST` requests.

fix

Configure `koa-override` with the `allowedMethods` option to include the desired request types, e.g., `app.use(override({ allowedMethods: ['POST', 'GET'] }));`

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/eggjs/koa-override ↗

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