TypeORM CommonJS TypeScript CLI Executor

0.3.20 · maintenance · verified Sun Apr 19

The `typeorm-ts-node-commonjs` package provides a command-line interface (CLI) wrapper specifically designed to execute TypeORM commands in TypeScript projects utilizing the CommonJS module system. It acts as an intermediary, configuring `ts-node/register` with appropriate settings to allow the TypeORM CLI (for tasks like migrations, schema synchronization, or entity generation) to correctly process TypeScript source files within a CommonJS environment. This package addresses compatibility challenges that historically arose when TypeORM's CLI, which typically requires `ts-node` for TypeScript compilation, encountered CommonJS module resolution. Although not directly maintained by the core TypeORM team, its usage is officially recommended in TypeORM's documentation for CommonJS TypeScript setups. The current stable version is 0.3.20, with the last update over a year ago, suggesting an infrequent release cadence driven by specific compatibility needs rather than active feature development.

Common errors

```
/usr/bin/env: 'node --require ts-node/register': No such file or directory
```
cause This error often occurs when running the CLI in Docker containers or environments where the shebang line's `node --require` parsing is problematic, or when `ts-node` is not correctly installed/accessible.

fix Ensure `ts-node` is installed and accessible in your environment. For `package.json` scripts, try replacing `"typeorm": "typeorm-ts-node-commonjs"` with a more explicit `"typeorm": "node --require ts-node/register ./node_modules/typeorm/cli.js"` or similar direct invocation, adjusting for CommonJS needs.
```
Error: Unable to open file: '/path/to/datasource.js'. Cannot find module '~/environment' Require stack: ...
```
cause This indicates a `ts-node` module resolution issue, often related to path aliases defined in `tsconfig.json` or incorrect `.js` extension resolution for TypeScript files.

fix Ensure your `tsconfig.json` paths are correctly configured for `ts-node` and that your TypeORM data source path is correct. You might need to add `--project tsconfig.json` (or a specific tsconfig file for TypeORM) to your CLI command to ensure `ts-node` picks up the correct configuration.
```
Error during migration run: Error: Connection lost: The server closed the connection.
```
cause While not directly caused by `typeorm-ts-node-commonjs`, this error has been reported in conjunction with it, particularly on newer Node.js versions, and is typically a database connection issue.

fix Verify your database connection parameters (host, port, username, password, database). Check firewall rules, network connectivity to the database, and ensure the database server is running and accessible. Sometimes, using an older stable Node.js version might temporarily resolve it if it's a transient compatibility issue.

Warnings

gotcha This package is not actively maintained by the TypeORM core team. While officially recommended in TypeORM documentation, the lack of recent updates (last publish over a year ago) means it might not immediately support the absolute latest Node.js, TypeORM, or `ts-node` versions without potential issues.
Fix: Monitor TypeORM's official documentation for alternative recommended approaches or be prepared to debug compatibility issues with newer dependency versions.
breaking As a wrapper around TypeORM and `ts-node`, this package's functionality is dependent on the APIs and behaviors of its underlying tools. Breaking changes in major versions of `typeorm` or `ts-node` could render this wrapper ineffective or cause unexpected behavior. This was notably observed during TypeORM's v0.3.0 transition.
Fix: Refer to the TypeORM and ts-node migration guides for breaking changes. If issues arise, consider manually configuring `ts-node` in your scripts instead of relying solely on this wrapper, or use `typeorm-ts-node-esm` for ESM projects.
gotcha The package name itself, `typeorm-ts-node-commonjs`, is used as the executable binary by TypeORM's CLI. Misconfigurations or attempts to use `typeorm` directly with TypeScript files in a CommonJS project will likely fail to resolve modules correctly.
Fix: Always ensure your `package.json` scripts explicitly call `typeorm-ts-node-commonjs` when running TypeORM CLI commands with TypeScript files in a CommonJS project, as shown in TypeORM's official documentation.

Install

npm install typeorm-ts-node-commonjs npm
yarn add typeorm-ts-node-commonjs yarn
pnpm add typeorm-ts-node-commonjs pnpm

Imports

npm script usage
```
"typeorm": "typeorm-ts-node-commonjs"
```
This package provides a CLI binary. It is most commonly referenced in `package.json` scripts to define the 'typeorm' command, allowing TypeORM to run with TypeScript in a CommonJS project. This pattern is officially recommended by TypeORM.
npx direct usage
wrong:
```
npx typeorm migration:run -d ./src/data-source.ts
```
correct:
```
npx typeorm-ts-node-commonjs migration:run -d ./src/data-source.ts
```
Direct invocation via `npx`. The 'wrong' example shows attempting to use the default `typeorm` binary directly with TypeScript source files in a CommonJS project, which this package is designed to resolve.
Explicit binary path
```
./node_modules/.bin/typeorm-ts-node-commonjs schema:sync -d ./config/ormconfig.ts
```
For explicit invocation of the locally installed binary, bypassing `npm run` or `npx`.

Quickstart

This quickstart demonstrates how to configure `package.json` scripts to use `typeorm-ts-node-commonjs` for TypeORM CLI commands in a TypeScript project configured for CommonJS modules, including a basic DataSource setup.

{
  "name": "my-typeorm-cjs-app",
  "version": "1.0.0",
  "main": "index.js",
  "type": "commonjs",
  "scripts": {
    "start": "node src/index.js",
    "typeorm": "typeorm-ts-node-commonjs",
    "typeorm:migration:generate": "npm run typeorm -- migration:generate -d ./src/data-source.ts ./src/migrations/MyNewMigration",
    "typeorm:migration:run": "npm run typeorm -- migration:run -d ./src/data-source.ts",
    "typeorm:schema:sync": "npm run typeorm -- schema:sync -d ./src/data-source.ts"
  },
  "dependencies": {
    "typeorm": "^0.3.20",
    "reflect-metadata": "^0.1.13",
    "pg": "^8.11.3"
  },
  "devDependencies": {
    "ts-node": "^10.9.1",
    "typescript": "^5.3.3",
    "typeorm-ts-node-commonjs": "^0.3.20"
  }
}
// src/data-source.ts
import "reflect-metadata";
import { DataSource } from "typeorm";
import { User } from "./entity/User";

export const AppDataSource = new DataSource({
    type: "postgres",
    host: process.env.DB_HOST ?? "localhost",
    port: parseInt(process.env.DB_PORT ?? "5432", 10),
    username: process.env.DB_USERNAME ?? "user",
    password: process.env.DB_PASSWORD ?? "password",
    database: process.env.DB_NAME ?? "mydatabase",
    synchronize: false,
    logging: false,
    entities: [User],
    migrations: [__dirname + "/migrations/**/*.ts"],
    subscribers: [],
});

// To run, assuming package.json is set up as above:
// npm install
// npm run typeorm:migration:generate

view raw JSON →