koa-methodoverride

2.0.0 verified Sat Apr 25 auth: no javascript maintenance

HTTP method override middleware for Koa, allowing clients to override the HTTP method (e.g., POST to PUT/DELETE) via X-HTTP-Method-Override header or query parameter. Version 2.0.0 is the latest stable release, designed for Koa v1 (generator-based) and Node >=4. It is a simple port of Express's method-override middleware. Unlike more modern alternatives, it does not support Koa v2 async/await natively and has minimal configuration options.

Common errors

error TypeError: methodOverride is not a function ↓

cause Importing package incorrectly (e.g., using default import in ESM).

fix

Use const methodOverride = require('koa-methodoverride'); (CommonJS).

error TypeError: app.use() requires a generator function ↓

cause Using Koa v2 (async/await) with this generator-based middleware.

fix

Use Koa v1 or wrap middleware with koa-convert: const convert = require('koa-convert'); app.use(convert(methodOverride()));

error Cannot find module 'koa-methodoverride' ↓

cause Package not installed or ESM import path incorrect.

fix

Run npm install koa-methodoverride; use require('koa-methodoverride') (no default export).

Warnings

breaking koa-methodoverride v2 does not support Koa v2 async/await syntax; middleware must be generator functions. ↓

fix Use koa-methodoverride@1 for Koa v1, or use a different method-override package compatible with Koa v2.

gotcha The middleware modifies `ctx.method` only; it does not alter the request body. You must still have a body parser if you expect a POST body. ↓

fix Ensure body parsing (e.g., koa-bodyparser) is used before methodOverride if you need to parse request body.

deprecated This package has not been updated since 2016 and is considered deprecated in favor of method-override for Koa v2. ↓

fix Migrate to a Koa v2 compatible package like koa-method-override (note: different name).

Install

npm install koa-methodoverride

yarn add koa-methodoverride

pnpm add koa-methodoverride

Imports

methodOverride

wrong

import methodOverride from 'koa-methodoverride';

correct

const methodOverride = require('koa-methodoverride');

This package is CJS-only; ESM import will fail.

default (function)
wrong
```
require('koa-methodoverride')(app);
```
correct
```
app.use(require('koa-methodoverride')());
```
It must be used as middleware, not invoked on the app directly.
with options
wrong
```
app.use(methodOverride({header: 'X-HTTP-Method'}));
```
correct
```
const methodOverride = require('koa-methodoverride'); app.use(methodOverride('X-HTTP-Method'));
```
Options are passed as string (header name) or object with `methods` array; passing an object with `header` key is not supported.

Quickstart

Shows minimal setup: add methodOverride middleware before your route handler, then send a POST with header X-HTTP-Method-Override: PUT to see the method change.

const Koa = require('koa');
const methodOverride = require('koa-methodoverride');

const app = new Koa();
app.use(methodOverride());
app.use(async (ctx) => {
  ctx.body = `Method: ${ctx.method}`;
});
app.listen(3000);