{"id":17750,"library":"koa-override","title":"Koa Method Override Middleware","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/eggjs/koa-override","tags":["javascript","koa-override","override-method","method-override","override","rewrite","typescript"],"install":[{"cmd":"npm install koa-override","lang":"bash","label":"npm"},{"cmd":"yarn add koa-override","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-override","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The default export is the middleware factory function. Since v4.0.0, it supports both ESM and CJS.","wrong":"import { override } from 'koa-override';","symbol":"override","correct":"import override from 'koa-override';"},{"note":"CommonJS syntax for Node.js environments. Works since v4.0.0 supports both CJS/ESM.","symbol":"override (CommonJS)","correct":"const override = require('koa-override');"},{"note":"`override` is a factory function that returns the actual middleware. It must be called, even with no options.","wrong":"app.use(override);","symbol":"Middleware usage","correct":"app.use(override());"}],"quickstart":{"code":"import Koa from 'koa';\nimport bodyParser from 'koa-bodyparser';\nimport override from 'koa-override';\n\nconst app = new Koa();\n\n// Add a body parser to handle _method in the request body\napp.use(bodyParser());\n\n// Apply the method override middleware\n// By default, it checks `body._method` then `X-HTTP-Method-Override` header\n// Overrides are only allowed on POST requests by default.\napp.use(override());\n\napp.use(async (ctx, next) => {\n  if (ctx.method === 'DELETE') {\n    ctx.body = `Received a simulated DELETE request for ${ctx.url}`;\n  } else if (ctx.method === 'PUT') {\n    ctx.body = `Received a simulated PUT request for ${ctx.url} with body: ${JSON.stringify(ctx.request.body)}`;\n  } else {\n    await next();\n  }\n});\n\napp.use(async (ctx) => {\n  ctx.body = `Received original ${ctx.method} request for ${ctx.url}`;\n});\n\nconst port = 3000;\napp.listen(port, () => {\n  console.log(`Server listening on http://localhost:${port}`);\n  console.log('Try POSTing to /test with X-HTTP-Method-Override: PUT, or with body: { \"_method\": \"DELETE\" }');\n});","lang":"typescript","description":"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`)."},"warnings":[{"fix":"Upgrade Node.js to version 18.19.0 or higher, or explicitly install `koa-override@3`.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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());`","message":"To 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you need to override methods on non-POST requests, configure `koa-override` with `app.use(override({ allowedMethods: ['POST', 'GET', 'PATCH'] }));`","message":"By 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Change `app.use(override)` to `app.use(override())`.","cause":"The `override` import refers to the middleware factory, which must be called to produce the actual middleware.","error":"TypeError: override is not a function"},{"fix":"Add a body parser middleware, like `koa-bodyparser`, before `koa-override`. Example: `app.use(bodyParser()); app.use(override());`","cause":"The request body, containing `_method`, has not been parsed yet when `koa-override` attempts to read it.","error":"Method override not working when using _method in form data"},{"fix":"Configure `koa-override` with the `allowedMethods` option to include the desired request types, e.g., `app.use(override({ allowedMethods: ['POST', 'GET'] }));`","cause":"By default, `koa-override` only applies method overriding to `POST` requests.","error":"Method override not working for GET requests or other non-POST methods"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}