# @nestjs/typeorm: the Nest integration package, and a README borrowed from the framework

> The official Nest module that wires TypeORM into the framework's dependency injection, released as native ESM in version 12. Its own README is a single install command copied from the Nest framework project, so most of what you need to evaluate lives in the docs site and the release notes instead.

**nestjs/typeorm** — TypeORM module for Nest framework (node.js)  🍇

- Repository: https://github.com/nestjs/typeorm
- Website: https://nestjs.com
- Stars: 2,164 · Forks: 233
- Language: TypeScript
- License: MIT
- Published: 2026-10-08 · Updated: 2026-10-08 · Language: en
- Canonical page: https://hysenlabs.com/projects/nestjs-typeorm

## One install command, then the documentation takes over

The installation section is a single line:

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

Two packages, because the integration is a bridge rather than a fork. You still install TypeORM itself, which keeps the ORM choice and the framework choice separable.

What follows that line is not documentation. The Quick Start section is a single link labelled Overview and Tutorial pointing at the Nest documentation site page on SQL techniques, so the tutorial for this package lives outside the repository. That is a deliberate division for a framework integration module: the module owns wiring, the docs site owns usage, and the duplication that would come from copying recipes into both places is avoided.

The consequence for a reader is real, though. If you want to know what this package configures for you, the answer is on a web page rather than in the repository, and the repository itself gives you almost nothing beyond its manifest and the release history. The sections below work with what is actually there.

## The README describes Nest, not the module

This is the most obvious thing to notice if you open the repository. The README opens with the Nest logo, then carries a set of build badges whose image paths point at the nestjs/nest repository rather than at nestjs/typeorm. The support section says Nest is an MIT-licensed open source project, and the license section says Nest is MIT licensed. Both statements are about the framework, and neither is about the package you came to read.

Only one line in the file describes this repository accurately, and it is the Description line: TypeORM module for Nest. Everything around it is the framework project's own README, kept largely intact so that the module repository still carries a familiar front page.

Set against that, the manifest is unambiguous. The name is `@nestjs/typeorm`, the description field reads Nest with the ORM noted in parentheses, the main entry is dist/index.js, and the exports map exposes the package root plus package.json and nothing else. So there are two different descriptions of the project sitting in the same repository, one written for humans browsing the framework organisation and one written for the package manager. When the two disagree, the manifest is the one your install will reflect.

Practically, this means you cannot learn anything about the module's behaviour from the README. The useful facts are the version, the peer range and the release notes.

## Version 12 turned the package into native ESM

The release history is where the substance is. Version 12.0.0, published on 2026-08-27, is a packaging rewrite rather than a feature release, and the notes say so directly. The package is published as pure ESM with type set to module, compiled with NodeNext, behind a proper exports map. The legacy root index.js and index.d.ts shims are gone, deep imports into build internals no longer resolve, and the minimum supported Node version is now 20.19.0.

The version number moved from 11.0.3 to 12.0.0 in the same step, to line up with the Nest 12 release train. The development dependencies reflect where the project builds: @nestjs/common and @nestjs/core are both pinned at 12.1.0, TypeScript is at roughly 7.0, vitest at 5.0.2, and types/node at 24.19.0.

The peer dependency range is more generous than the dev environment, which is worth noticing. The declared peers accept @nestjs/common and @nestjs/core at 10, 11 or 12, so the module claims compatibility with three major versions of the framework even though it is developed against the newest one. That gap is normal for an integration package and it is also the reason the major bump is riskier than the notes suggest: the same build is expected to load in a Nest 10 application that predates the ESM rewrite by years.

## The next patch contradicts the migration announcement

Two releases in a row say opposite things about CommonJS. The 12.0.0 notes carry a section headed require(esm), followed by the sentence that you do not need to convert your app to ESM, followed by the explanation that CommonJS applications still work thanks to Node's require of an ES module support.

Four days later, version 12.0.1 shipped a single change: add a default condition to exports so CommonJS can resolve the package. That is a fix to resolution, not to interop. In other words, the announcement described the intent, and the patch fixed the case where the CommonJS resolver could not find the entry point at all. Both releases are in the history and neither is wrong about what it did.

This is the kind of contradiction worth more than a paragraph, because it tells you exactly what to check. If your application is CommonJS, do not rely on the migration note alone. Install 12.0.1 or later, then verify two things directly in your own project: that requiring the package root resolves at all, and that the deep paths you import still exist. The release notes for 12.0.0 state that deep imports into build internals are no longer resolvable and that you should import from the package root, which means any line of the form an import from a dist subpath in your codebase is a breaking change waiting to happen.

The 12.0.2 release continues in the same practical register, with two fixes: throwing when an EntitySchema has no target or name when building its injection token, and resolving the named data source on shutdown for async registrations. Both are the kind of defect that only shows up in a real application doing real lifecycle work, which is a fair signal about where this package's risk lives.

## A Postgres test service published on the MySQL port

The repository carries a docker-compose.yml for its own test runs, and it contains a detail that will waste an afternoon if you copy it.

```yaml
services:
  postgres:
    image: postgres:18.6
    environment:
      POSTGRES_USER: root
      POSTGRES_PASSWORD: root
      POSTGRES_DB: test
    ports:
      - "3306:5432"
```

The service is Postgres and the container port is correct at 5432, but the published host port is 3306, which is MySQL's port. Meanwhile the development dependencies include both pg at 8.23.0 and mysql at 2.18.1, so the test suite clearly exercises more than one database driver while the compose file defines only the Postgres one. Both facts come from the repository: a compose file mapping Postgres to 3306, and a dependency list covering two drivers.

If you adopt this file, change the host side of the mapping to something free, and if you want to reproduce the suite locally, expect to supply your own MySQL service, since the file does not define one. It is a small thing, but it is the kind of thing that makes a test fixture misleading when two projects on your machine want port 3306 at once.

## Where the repository is disciplined and where it is empty

The tree is short and says something about how this project is run. There is a lib directory for source, tests for the suite, a .circleci directory for continuous integration, and a set of release tooling files: release-it configuration, a commitlint config, husky hooks wired through the prepare script, and renovate for dependency updates. Linting runs through oxlint, and the tree carries oxlint.config.ts with no ESLint configuration at all, so the linter choice was made deliberately rather than by inheritance.

The test scripts are also deliberate. Both the end-to-end run and its watch variant pass `--sequence.sequential`, which tells you the tests share state and are not safe to parallelise, and supertest plus @nestjs/platform-express in the dev dependencies confirm the suite drives a real HTTP application rather than mocking the framework. Coverage is not configured in the manifest, so there is no coverage threshold to read as a quality signal.

What is missing is as informative as what is present. No source file from lib is documented anywhere in the README, no example directory exists, and there is no sample application. For a package this small that may be correct, since its job is wiring rather than teaching. But it means the only way to know what the module gives you is to read the Nest documentation page the README links to, and then read the code.

## Conclusion

This package is the right choice if you have already chosen Nest and TypeORM, because it is the maintained bridge between them and it is versioned in step with the framework. It is the wrong package to evaluate for its own sake: the README carries one install command and defers everything else to docs.nestjs.com, so judge it on the peer dependency range and on the release notes rather than on its front page. Two specifics deserve a look before you upgrade. Version 12 requires Node 20.19 or newer and ships as native ESM, and the immediately following patch, 12.0.1, had to add a default condition to the exports map before CommonJS callers could resolve the package, so if you are still on a CommonJS build, read that patch note and try a require of the package root before committing to the major bump.

## FAQ

### Do I still need to install TypeORM alongside @nestjs/typeorm?

Yes. The README's install line is `npm i --save @nestjs/typeorm typeorm`, two packages in one command. The Nest package is an integration layer and does not bundle the ORM, so the ORM is a separate dependency you choose and version yourself.

### Which versions of Nest does @nestjs/typeorm support?

The peer dependencies accept @nestjs/common and @nestjs/core across major versions 10, 11 and 12. The development dependencies pin both at 12.1.0, so the module is built and tested against the newest line while claiming compatibility with the older ones.

### Does @nestjs/typeorm 12 work in a CommonJS application?

The 12.0.0 notes say CommonJS still works through Node's require of an ES module, but the very next release, 12.0.1, added a default condition to the exports map so CommonJS could resolve the package at all. Use 12.0.1 or later and verify that requiring the package root resolves in your project.

### What Node version does @nestjs/typeorm require now?

Version 12 raised the minimum to Node 20.19.0, and the manifest's engines field states the same bound. Before that, the package was CommonJS-compatible and built with a looser toolchain.

## Sources

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

---

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