Packages

@xtaskjs/typeorm

TypeORM integration with datasource registration, startup migrations and seeders, and repository injection helpers.

npm install @xtaskjs/typeorm typeorm reflect-metadata Package path: packages/typeorm

Overview

What this package owns in the runtime

TypeORM support attaches datasource lifecycle to xtask startup and shutdown. It gives the container a standard way to inject datasources and repositories, while providing migration and seeder registries that can run during bootstrap.

What it provides

Registers datasources during bootstrap and destroys them during app.close().
Runs pending migrations and ordered seeders when runMigrationsOnServerStart and runSeedersOnServerStart are enabled.
Supports TypeOrmMigration() and TypeOrmSeeder() decorators for registry-based startup execution.
Re-exports TypeORM decorators and APIs from one package entry point.
Supports datasource decorators and injection helpers.
Fits both SQLite demos and larger multi-datasource applications.

How it fits

Activated automatically when the package exports initializeTypeOrmIntegration().
Merges migrations defined in datasource options with classes registered by TypeOrmMigration() for the same datasource name.
Executes registered seeders in order after datasource initialization when runSeedersOnServerStart is enabled.
Used with Fastify in the SQLite sample and with Postgres in this website project.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

4/5

Dependency Injection

4/5

Persistence

5/5

Integrations

5/5

Security

2/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

During CreateApplication()

The integration opens datasources, publishes repository and datasource tokens into the container, and makes them injectable to services and controllers.

During app.close()

Datasource connections are destroyed automatically so database shutdown is aligned with the main application lifecycle.

API Surface

Representative exports from the upstream package

TypeORM bridge

registerTypeOrmDataSource
TypeOrmDataSource
InjectDataSource
InjectRepository
TypeOrmMigration
TypeOrmSeeder

Re-exported ORM APIs

DataSource
Entity
Column
PrimaryGeneratedColumn
OneToMany
ManyToOne
Repository

Lifecycle surface

initializeTypeOrmIntegration
shutdownTypeOrmIntegration

Usage

Typical adoption flow

1. Register datasource definitions

Describe your datasource once and keep entities, migrations, and connection details close to the app entry point.

2. Inject repositories or datasources

Use the xtask TypeORM decorators and tokens to inject repositories into DI-managed services instead of constructing them manually.

3. Let lifecycle manage connections

Rely on bootstrap and shutdown hooks instead of manual initialize() and destroy() calls across the codebase.

Example

Reference snippet

Datasource, migration, and seeder registration

import {
  DataSource,
  MigrationInterface,
  QueryRunner,
  TypeOrmDataSource,
  TypeOrmMigration,
  TypeOrmSeeder,
} from "@xtaskjs/typeorm";
import { UserEntity } from "./user.entity";

@TypeOrmDataSource({
  name: "default",
  type: "sqlite",
  database: process.env.DB_PATH || "xtask-typeorm.sqlite",
  entities: [UserEntity],
  synchronize: false,
  runMigrationsOnServerStart: true,
  runSeedersOnServerStart: true,
})
export class DatabaseConfig {}

@TypeOrmMigration({ dataSourceName: "default" })
export class CreateUsersTable1700000000000 implements MigrationInterface {
  async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query("CREATE TABLE IF NOT EXISTS users (id integer primary key autoincrement, name varchar(120) not null)");
  }

  async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query("DROP TABLE IF EXISTS users");
  }
}

@TypeOrmSeeder({ dataSourceName: "default", order: 1 })
export class DefaultUsersSeeder {
  async run(dataSource: DataSource): Promise<void> {
    await dataSource.query("INSERT INTO users (name) VALUES ('Ada Lovelace')");
  }
}

Samples

Official samples to inspect next

Reference samples: 04-typeorm_app