# @nestjs/mongoose wires Mongoose into the Nest dependency injection container

> The @nestjs/mongoose package is the official Mongoose module for the Nest framework, and its real job is to turn a connection string into an injectable model and connection provider rather than to talk to MongoDB itself. It suits a Nest application that already wants Mongoose, and it does not add a query layer over Mongoose.

**nestjs/mongoose** — Mongoose module for Nest framework (node.js) 🍸

- Repository: https://github.com/nestjs/mongoose
- Website: https://nestjs.com
- Stars: 572 · Forks: 118
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/nestjs-mongoose

## What the module actually contributes

The repository is described in one line as the Mongoose module for Nest, and the framing matters. This package is not a database abstraction and it does not replace Mongoose. Its job is the glue between two things that already exist: the Nest framework, which is described in the documentation as a progressive Node.js framework for building efficient and scalable server-side applications, and Mongoose, the object document mapper. What the module provides is a way to declare a connection and to have models injectable, so that a service can ask the container for a model rather than importing one at module scope. The application code still calls Mongoose APIs, with the same schemas, the same queries and the same middleware, and the only thing that changes is where the model instance comes from. The repository layout matches a focused integration package rather than a framework. There is a lib/ directory for the source, tests/ for the test suite, and the usual project files including a tsconfig.build.json, an oxlint.json, a vitest.config.ts and a .release-it.json for releases.

## Installing the module and its peer dependencies

Installation is a single npm command that pulls in both the module and the ODM it wraps.

```bash
$ npm i --save @nestjs/mongoose mongoose
```

The dollar sign is the convention in the documentation for a command with the package manager prompt visible, and the save flag records both packages as dependencies. The mongoose argument is not optional advice, it is the peer. The manifest lists no runtime dependencies of its own, only peer dependencies, which is the clearest signal of how the package is built. The peer ranges are @nestjs/common and @nestjs/core at ^11.0.0 or ^12.0.0, mongoose at ^7.0.0, ^8.0.0 or ^9.0.0, and rxjs at ^7.0.0. That means a project on Mongoose 6 or Nest 10 is outside the supported range, and the Nest 12 support is recent enough to matter given the release history. The package is published as @nestjs/mongoose at version 12.0.0, with 11.0.4 in December 2025 and 11.0.3 in March 2025 before it, and the last push to the repository was on 2026-10-19.

## The module is ESM only, and that is a packaging decision

The manifest sets type to module, with main pointing at dist/index.js and types at dist/index.d.ts, and the exports map offering a single root entry with a types condition and a default condition. That is worth noticing for anyone upgrading from an earlier major, because a package that was CommonJS and is now ESM only changes how it can be consumed from a Node project without a transpiling build step. A Nest application is usually compiled with TypeScript, so the practical impact is limited, but tooling that requires a require of the package, such as a CommonJS Jest setup, will need adjusting. The build itself is a plain tsc invocation against a dedicated build config, with the dist directory removed first, and the publish scripts run that build before pushing to npm, so the published tarball always contains freshly compiled output. The package declares sideEffects as false, which lets a bundler drop it if it can prove nothing from it is used, a small but real benefit in a server bundle that pulls in a lot of framework packages.

## How the connection becomes an injectable provider

The design goal behind the module is the Nest convention of keeping external resources inside the framework's lifecycle, so the connection is created, observed and closed by the same mechanism that manages the rest of the application. In practice that means the application declares a connection, and the models built on that connection become providers that a service can inject. The documentation keeps the reference details on the Nest side rather than repeating them here, pointing to the overview and tutorial for the MongoDB technique and to the Nest documentation portal. What the repository does not spell out is the fine detail, and for an evaluation that is the gap to be aware of. The package is small enough that the README is short, the quick start is a link rather than a code sample, and there is no walkthrough of what happens on a failed connection at boot, on retry behaviour, or on the difference between a connection per feature module and a shared one. Those behaviours are the ones you will want to know about, and the tutorial linked from the repository is where to read them. The docker-compose.yml at the root is a hint about the local development story, and it is minimal.

## The local MongoDB setup for running the tests

The repository includes a docker-compose.yml, and it is three services of specification long, which tells you the whole local development story.

```yaml
version: "3"

services:
  mongodb:
    image: mongo:latest
    environment:
      - MONGODB_DATABASE="test"
    ports:
      - 27017:27017
```

The only service is MongoDB, taken from the latest tag, with a database named test and the standard port published to the host. The absence of a web service is the point, because this package is a library and there is no application to run. The standard port mapping means a locally installed mongod on 27017 will conflict, which is a common first stumble, and using the latest image tag means a change in MongoDB major version can arrive without any change in the repository. The test script in the manifest is named test:e2e and runs vitest, with a companion test:e2e:dev for watch mode, and the dev dependencies include supertest, which indicates the suite drives HTTP level assertions against a running application rather than only unit tests of the module.

## The toolchain: oxlint, vitest, husky and release-it

The manifest is a good record of how the project works day to day. Linting runs oxlint against the lib directory with a dedicated configuration file, and formatting is Prettier over the TypeScript sources, which is a noticeably modern combination for a Nest package given the age of the framework's own tooling. Tests run under Vitest, and the presence of vite in the dev dependencies confirms the runner rather than Jest, while supertest is there for the request level assertions. Hooks are handled by husky with a prepare script that installs them, and a precommit script that runs lint-staged. The lint-staged configuration is notable because it is set to match nothing, the glob pattern for TypeScript and JSON files is followed by an empty array, so staged changes are not rewritten by a formatter during the commit itself. Releases are automated with release-it, driven by a .release-it.json file, and the publish scripts distinguish a normal npm release from a next tag for prereleases, each of them running the build first. Dependency updates are handled by renovate, and there is a .commitlintrc.json enforcing conventional commits, which pairs with the commitlint packages in the dev dependencies. A .nvmrc file pins the Node version for contributors.

## Where the choice of Mongoose itself is the real decision

The boundary of this package is best understood by looking at what it does not do. It does not give you a query builder, a schema DSL of its own, or any layer above Mongoose. The model you inject is a Mongoose model, the schema you write is a Mongoose schema, and the plugin ecosystem you can use is Mongoose's. So the evaluation question is not really about this module but about Mongoose, with the module making that choice sit inside Nest's dependency injection model rather than at module scope. Two practical consequences follow. The first is that the module is where you decide how connections are scoped, whether one connection for the whole application or one per feature, and the second is that a project which later wants to change ODM has to change more than an import, since the provider registration is part of the module setup. The package's own version history also suggests a moving target for anyone pinning: three of the last four releases are majors or near-majors within a year, so the peer range moves, and the Nest 12 support in the current release is the kind of change that arrives with the framework rather than with the ODM.

## Conclusion

Adopt @nestjs/mongoose if your application is already built on Nest and has chosen Mongoose, since the module gives you models and the connection as injectable providers and keeps them inside the framework's lifecycle rather than in module-level singletons. Do not adopt it if you are starting a new project and have not picked a data layer, because the choice of Mongoose over the native driver or over Prisma is the decision this package encodes. Verify two things before you pin a version: that the Mongoose major you run is in the supported range, since the peer dependencies allow 7, 8 and 9 but not earlier lines, and that the Nest major you run is supported too, since the same peer range covers Nest 11 and 12. The practical first step is to install the module with its Mongoose peer, follow the MongoDB technique guide linked from the repository, and confirm the connection provider resolves before you write your first model.

## FAQ

### What does the @nestjs/mongoose package do?

It is the Mongoose module for the Nest framework. It lets a Nest application register a MongoDB connection and obtain Mongoose models through the framework's dependency injection, rather than importing model instances at module scope.

### How do I install @nestjs/mongoose?

Run npm i --save @nestjs/mongoose mongoose, which installs the module and the ODM it wraps. The manifest lists no runtime dependencies of its own, only peer dependencies.

### Which versions of Mongoose and Nest are supported?

The peer dependencies allow mongoose at ^7.0.0, ^8.0.0 or ^9.0.0, and @nestjs/common and @nestjs/core at ^11.0.0 or ^12.0.0, along with rxjs at ^7.0.0. Older lines such as Mongoose 6 are outside the supported range.

### How do I run the @nestjs/mongoose tests locally?

Start MongoDB with the included docker-compose.yml, which runs the mongo:latest image with a database named test on port 27017, and then run the test:e2e script, which executes vitest. A companion test:e2e:dev script runs vitest in watch mode.

### Is @nestjs/mongoose CommonJS or ESM?

It is ESM only. The manifest sets type to module, with main pointing at dist/index.js and the exports map offering a root entry with types and default conditions, so a project consuming it with require needs adjustment.

## Sources

- [License: MIT](https://github.com/nestjs/mongoose/blob/master/LICENSE)
- [nestjs/mongoose on GitHub](https://github.com/nestjs/mongoose)
- [Project website](https://nestjs.com)
- [README](https://github.com/nestjs/mongoose/blob/master/README.md)
- [Releases](https://github.com/nestjs/mongoose/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nestjs-mongoose