{"id":14993,"library":"typeorm-ts-node-commonjs","title":"TypeORM CommonJS TypeScript CLI Executor","description":"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.","status":"maintenance","version":"0.3.20","language":"javascript","source_language":"en","source_url":"git://github.com/alxndrsn/alias-in-wonderland","tags":["javascript"],"install":[{"cmd":"npm install typeorm-ts-node-commonjs","lang":"bash","label":"npm"},{"cmd":"yarn add typeorm-ts-node-commonjs","lang":"bash","label":"yarn"},{"cmd":"pnpm add typeorm-ts-node-commonjs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package wraps the TypeORM CLI, requiring TypeORM to be installed in the project.","package":"typeorm","optional":false},{"reason":"This package configures and utilizes ts-node to execute TypeScript files within a CommonJS context for TypeORM commands.","package":"ts-node","optional":false},{"reason":"Required for compiling and executing TypeScript files.","package":"typescript","optional":false}],"imports":[{"note":"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.","symbol":"npm script usage","correct":"\"typeorm\": \"typeorm-ts-node-commonjs\""},{"note":"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.","wrong":"npx typeorm migration:run -d ./src/data-source.ts","symbol":"npx direct usage","correct":"npx typeorm-ts-node-commonjs migration:run -d ./src/data-source.ts"},{"note":"For explicit invocation of the locally installed binary, bypassing `npm run` or `npx`.","symbol":"Explicit binary path","correct":"./node_modules/.bin/typeorm-ts-node-commonjs schema:sync -d ./config/ormconfig.ts"}],"quickstart":{"code":"{\n  \"name\": \"my-typeorm-cjs-app\",\n  \"version\": \"1.0.0\",\n  \"main\": \"index.js\",\n  \"type\": \"commonjs\",\n  \"scripts\": {\n    \"start\": \"node src/index.js\",\n    \"typeorm\": \"typeorm-ts-node-commonjs\",\n    \"typeorm:migration:generate\": \"npm run typeorm -- migration:generate -d ./src/data-source.ts ./src/migrations/MyNewMigration\",\n    \"typeorm:migration:run\": \"npm run typeorm -- migration:run -d ./src/data-source.ts\",\n    \"typeorm:schema:sync\": \"npm run typeorm -- schema:sync -d ./src/data-source.ts\"\n  },\n  \"dependencies\": {\n    \"typeorm\": \"^0.3.20\",\n    \"reflect-metadata\": \"^0.1.13\",\n    \"pg\": \"^8.11.3\"\n  },\n  \"devDependencies\": {\n    \"ts-node\": \"^10.9.1\",\n    \"typescript\": \"^5.3.3\",\n    \"typeorm-ts-node-commonjs\": \"^0.3.20\"\n  }\n}\n// src/data-source.ts\nimport \"reflect-metadata\";\nimport { DataSource } from \"typeorm\";\nimport { User } from \"./entity/User\";\n\nexport const AppDataSource = new DataSource({\n    type: \"postgres\",\n    host: process.env.DB_HOST ?? \"localhost\",\n    port: parseInt(process.env.DB_PORT ?? \"5432\", 10),\n    username: process.env.DB_USERNAME ?? \"user\",\n    password: process.env.DB_PASSWORD ?? \"password\",\n    database: process.env.DB_NAME ?? \"mydatabase\",\n    synchronize: false,\n    logging: false,\n    entities: [User],\n    migrations: [__dirname + \"/migrations/**/*.ts\"],\n    subscribers: [],\n});\n\n// To run, assuming package.json is set up as above:\n// npm install\n// npm run typeorm:migration:generate\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Monitor TypeORM's official documentation for alternative recommended approaches or be prepared to debug compatibility issues with newer dependency versions.","message":"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.","severity":"gotcha","affected_versions":">=0.3.20"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.3.0 of TypeORM"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"/usr/bin/env: 'node --require ts-node/register': No such file or directory"},{"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.","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.","error":"Error: Unable to open file: '/path/to/datasource.js'. Cannot find module '~/environment' Require stack: ..."},{"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.","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.","error":"Error during migration run: Error: Connection lost: The server closed the connection."}],"ecosystem":"npm"}