Registry / database / koa-mongo

koa-mongo

JSON →
library1.9.3jsnpmunverified

koa-mongo is a MongoDB middleware for Koa 2 that provides connection pool management via generic-pool. Version 1.9.3 is the latest stable release. It attaches an initialized MongoClient to `ctx.mongo` and a database handle to `ctx.db`, allowing direct access to native MongoDB driver methods. Supports both URI and separate host/port configuration. Compared to alternatives like koa-mongodb, koa-mongo is lightweight and explicitly integrates with Koa's middleware pattern, but relies on the deprecated MongoDB driver v3.x API and lacks built-in TypeScript types.

database
npm install koa-mongo
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · KOA-MONGO
K
koa-mongo
databasejavascriptv1.9.3
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

mongo
✓ import mongo from 'koa-mongo'
✗ const mongo = require('koa-mongo').default
Default export; CommonJS require works directly (const mongo = require('koa-mongo')).
mongo.ObjectId
✓ import mongo from 'koa-mongo'; const { ObjectId } = mongo
✗ import { ObjectId } from 'koa-mongo'
ObjectId is a property on the default export, not a named export.
mongo
✓ const mongo = require('koa-mongo')
CommonJS require works; no named exports available.

Demonstrates basic setup with URI configuration and a simple insert operation using ctx.db.

const Koa = require('koa'); const mongo = require('koa-mongo'); const app = new Koa(); app.use(mongo({ uri: process.env.MONGO_URI || 'mongodb://localhost:27017/test' })); app.use(async (ctx) => { const result = await ctx.db.collection('users').insertOne({ name: 'example' }); ctx.body = { id: result.insertedId }; }); app.listen(3000, () => console.log('Server running on port 3000'));
Debug
Known issues
deprecatedMongoDB driver v3.x methods like insert() and remove() are deprecated; use insertOne()/insertMany() and deleteOne()/deleteMany() instead.
fix
Replace insert() with insertOne() and remove() with deleteOne() or deleteMany(), and ensure _id is a string if needed.
affects: >=1.0
deprecatedThe default connection uses host/port and db options; the URI option is preferred but may not support all MongoDB connection string options.
fix
Use the uri option for connection and pass native driver options as a second argument.
affects: <1.9
gotchactx.db is bound to a specific database; if you need multiple databases, you must call ctx.mongo.db(dbName) manually.
fix
Use ctx.mongo.db('otherDb') to access a different database.
affects: >=1.0
gotchaLibrary does not export TypeScript type definitions; you may encounter type errors in TS projects.
fix
Install @types/koa-mongo or write custom type declarations.
affects: >=1.0
breakingIn koa-mongo 1.x, the middleware expects koa@2; it will not work with koa@1.
fix
Use koa@2.x or higher.
affects: >=1.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'collection')
Middleware not applied or ctx.db is undefined because connection failed.
fix
Ensure mongo() middleware is added before any route handlers and that the MongoDB server is running.
MongoError: Cannot find module 'mongodb'
mongodb is not installed as a peer dependency.
fix
Run: npm install mongodb
TypeError: ctx.db.collection(...).insert is not a function
Using deprecated insert() method which is removed in newer mongodb driver versions.
fix
Replace insert() with insertOne() or insertMany().
MongoError: Authentication failed.
Incorrect credentials or authSource not set.
fix
Provide user, pass, and authSource in options or use a URI with authentication.
Upgrade
Version history
1.9.3latest on npm
Audit
Dependencies
mongodboptionalPeer dependency for MongoDB driver; koa-mongo uses MongoClient from mongodb package
generic-poolrequiredUsed for connection pool management; bundled dependency
Agent activity
5 hits · last 30 days
node
4
Resources
githubhttps://github.com/nswbmw/koa-mongo ↗
packagekoa-mongo ↗
homepagehttps://github.com/nswbmw/koa-mongo#readme ↗
koa-mongo — npm install koa-mongo · libregistry