NestJS + TypeORM Integration Skill

Purpose

You are a specialized assistant for integrating TypeORM with NestJS in a clean, scalable, and production-friendly way.

Use this skill to:

• Set up TypeORM in a NestJS project (data source, modules, config)
• Define or refactor entities and their relations
• Configure migrations and environment-specific DB settings
• Wire repositories into services using Nest DI
• Implement transactions and query patterns safely
• Optimize DB usage (indexes, query patterns, relations loading) at a structural level

Do not use this skill for:

• General NestJS module/service/controller scaffolding → use nestjs-project-scaffold / nestjs-modules-services-controllers
• Authentication logic → use nestjs-authentication
• Supabase-specific flows → use Supabase skills (unless Supabase Postgres is accessed via TypeORM as a plain DB)

If CLAUDE.md exists, follow its rules on database choice, naming conventions, and directory layout.

When To Apply This Skill

Trigger this skill when the user asks for things like:

• “Set up TypeORM in this NestJS API.”
• “Create entities and migrations for these tables in NestJS + TypeORM.”
• “Wire repositories into my Nest services.”
• “Fix or refactor our NestJS TypeORM config.”
• “Add relations between these entities and update the service logic.”
• “Handle transactions for this multi-step operation.”

Avoid using this skill when:

• Only high-level REST API contracts are changing without DB impact.
• Only pure in-memory logic is being implemented.

Assumptions & Defaults

Unless the project states otherwise, assume:

• Database: Postgres (can be adapted to MySQL, SQLite, etc.)
• TypeORM version: current stable for NestJS
• Connection is configured via Nest’s TypeOrmModule
• Config is environment-driven via @nestjs/config and .env files
• Entities live in src/modules/<feature>/entities or src/entities depending on project style
• Migrations live in src/migrations or migrations directory

High-Level Architecture

Recommended structure (adapt as needed):

text
1project-root/
2  src/
3    config/
4      database.config.ts
5    modules/
6      user/
7        user.module.ts
8        user.service.ts
9        user.controller.ts
10        entities/
11          user.entity.ts
12      post/
13        post.module.ts
14        post.service.ts
15        post.controller.ts
16        entities/
17          post.entity.ts
18    infrastructure/
19      database/
20        ormconfig.ts or data-source.ts (optional central place)
21  migrations/
22    1710000000000-CreateUserTable.ts
23    1710000001000-CreatePostTable.ts

This skill should align with the existing structure rather than forcing a totally new one, unless the project is greenfield.

Step-by-Step Workflow

When this skill is active, follow these steps:

1. Set Up TypeORM Module Configuration

If TypeORM is not configured yet:

• Install TypeORM + DB driver for the chosen database.
• Configure TypeOrmModule in AppModule or a dedicated DatabaseModule.

Example using @nestjs/config:

ts
1// src/config/database.config.ts
2import { registerAs } from "@nestjs/config";
3
4export default registerAs("database", () => ({
5  type: "postgres",
6  host: process.env.DB_HOST ?? "localhost",
7  port: parseInt(process.env.DB_PORT ?? "5432", 10),
8  username: process.env.DB_USERNAME ?? "postgres",
9  password: process.env.DB_PASSWORD ?? "postgres",
10  database: process.env.DB_NAME ?? "app_db",
11}));

ts
1// src/app.module.ts
2import { Module } from "@nestjs/common";
3import { ConfigModule, ConfigService } from "@nestjs/config";
4import databaseConfig from "./config/database.config";
5import { TypeOrmModule } from "@nestjs/typeorm";
6
7@Module({
8  imports: [
9    ConfigModule.forRoot({
10      isGlobal: true,
11      load: [databaseConfig],
12    }),
13    TypeOrmModule.forRootAsync({
14      inject: [ConfigService],
15      useFactory: (config: ConfigService) => {
16        const db = config.get("database");
17        return {
18          ...db,
19          autoLoadEntities: true,
20          synchronize: false, // prefer migrations in production
21        };
22      },
23    }),
24    // feature modules...
25  ],
26})
27export class AppModule {}

Key rules:

• synchronize: false in all non-dev environments (this skill encourages migrations).
• autoLoadEntities: true is acceptable for many apps; for stricter control, explicitly list entities.

2. Environment Variables

Ensure .env (and .env.example) contain:

env
1DB_HOST=localhost
2DB_PORT=5432
3DB_USERNAME=postgres
4DB_PASSWORD=postgres
5DB_NAME=app_db

This skill should help keep secrets out of code and only in env/config.

3. Entities Design

For each feature, create entity classes:

ts
1// src/modules/user/entities/user.entity.ts
2import {
3  Column,
4  CreateDateColumn,
5  Entity,
6  PrimaryGeneratedColumn,
7  UpdateDateColumn,
8} from "typeorm";
9
10@Entity({ name: "users" })
11export class User {
12  @PrimaryGeneratedColumn("uuid")
13  id!: string;
14
15  @Column({ unique: true })
16  email!: string;
17
18  @Column()
19  passwordHash!: string;
20
21  @Column({ default: true })
22  isActive!: boolean;
23
24  @CreateDateColumn()
25  createdAt!: Date;
26
27  @UpdateDateColumn()
28  updatedAt!: Date;
29}

Relations example:

ts
1// src/modules/post/entities/post.entity.ts
2import {
3  Column,
4  CreateDateColumn,
5  Entity,
6  ManyToOne,
7  PrimaryGeneratedColumn,
8} from "typeorm";
9import { User } from "../../user/entities/user.entity";
10
11@Entity({ name: "posts" })
12export class Post {
13  @PrimaryGeneratedColumn("uuid")
14  id!: string;
15
16  @Column()
17  title!: string;
18
19  @Column({ type: "text" })
20  content!: string;
21
22  @ManyToOne(() => User, (user) => user.posts, { onDelete: "CASCADE" })
23  author!: User;
24
25  @CreateDateColumn()
26  createdAt!: Date;
27}

This skill should:

• Encourage using uuid or bigint for IDs consistently (per project preference).
• Use clear relation options (onDelete, eager, lazy) thoughtfully.
• Avoid putting heavy business logic directly into entities.

4. Module & Repository Wiring

Use TypeOrmModule.forFeature to inject repositories into feature modules:

ts
1// src/modules/user/user.module.ts
2import { Module } from "@nestjs/common";
3import { TypeOrmModule } from "@nestjs/typeorm";
4import { User } from "./entities/user.entity";
5import { UserService } from "./user.service";
6import { UserController } from "./user.controller";
7
8@Module({
9  imports: [TypeOrmModule.forFeature([User])],
10  controllers: [UserController],
11  providers: [UserService],
12  exports: [UserService],
13})
14export class UserModule {}

In UserService, inject the repository:

ts
1// src/modules/user/user.service.ts
2import { Injectable } from "@nestjs/common";
3import { InjectRepository } from "@nestjs/typeorm";
4import { Repository } from "typeorm";
5import { User } from "./entities/user.entity";
6import { CreateUserDto } from "./dto/create-user.dto";
7
8@Injectable()
9export class UserService {
10  constructor(
11    @InjectRepository(User)
12    private readonly usersRepo: Repository<User>,
13  ) {}
14
15  create(dto: CreateUserDto) {
16    const entity = this.usersRepo.create({
17      email: dto.email,
18      passwordHash: dto.passwordHash,
19    });
20    return this.usersRepo.save(entity);
21  }
22
23  findAll() {
24    return this.usersRepo.find();
25  }
26
27  findOne(id: string) {
28    return this.usersRepo.findOne({ where: { id } });
29  }
30
31  // etc...
32}

This skill should enforce:

• Repositories are injected via DI, not instantiated manually.
• Services depend on repositories, not on the data source directly (except in advanced scenarios).

5. Migrations

Encourage using migrations instead of synchronize for schema changes.

• Create a data-source.ts file if needed for CLI migrations:

ts
1// data-source.ts (or src/infrastructure/database/data-source.ts)
2import "reflect-metadata";
3import { DataSource } from "typeorm";
4import databaseConfig from "./src/config/database.config";
5import { config as loadEnv } from "dotenv";
6
7loadEnv();
8
9const db = databaseConfig();
10
11export const AppDataSource = new DataSource({
12  type: "postgres",
13  host: db.database.host,
14  port: db.database.port,
15  username: db.database.username,
16  password: db.database.password,
17  database: db.database.database,
18  entities: ["src/**/*.entity.{ts,js}"],
19  migrations: ["migrations/*.{ts,js}"],
20});

• Add package.json scripts for migrations (exact form depends on project):

jsonc
1{
2  "scripts": {
3    "typeorm:run": "typeorm-ts-node-commonjs migration:run -d data-source.ts",
4    "typeorm:revert": "typeorm-ts-node-commonjs migration:revert -d data-source.ts",
5    "typeorm:generate": "typeorm-ts-node-commonjs migration:generate -d data-source.ts migrations/AutoMigration"
6  }
7}

This skill should:

• Prefer explicit migration generation (migration:generate) over schema sync.
• Keep migration files small, ordered, and committed to version control.

6. Transactions & Complex Operations

For operations that require multiple DB writes, this skill should:

• Use QueryRunner or manager.transaction where needed.

Example:

ts
1import { DataSource } from "typeorm";
2
3@Injectable()
4export class OrderService {
5  constructor(private readonly dataSource: DataSource) {}
6
7  async createOrderAndItems(dto: CreateOrderDto) {
8    return this.dataSource.transaction(async (manager) => {
9      const order = manager.create(Order, { /* ... */ });
10      await manager.save(order);
11
12      const items = dto.items.map((itemDto) =>
13        manager.create(OrderItem, {
14          order,
15          // ...
16        }),
17      );
18      await manager.save(items);
19
20      return order;
21    });
22  }
23}

Guidelines:

• Use transactions only where needed; avoid wrapping everything by default.
• Handle error propagation correctly; if the transaction throws, it rolls back.

7. Performance & Query Patterns

This skill should guide towards:

• Using select and projections instead of always loading entire entities.
• Avoiding N+1 queries with relation loading patterns when necessary.
• Adding indexes in migrations for frequently queried columns.
• Using pagination strategies (offset/limit or cursor-based) for large lists.

8. Refactoring Existing TypeORM Usage

When refactoring:

• Identify anti-patterns:
  • Manual connection creation (bypassing Nest DI)
  • Direct use of global getRepository instead of injected repositories
  • synchronize: true in production
• Replace with:
  • TypeOrmModule configuration
  • Injected Repository<T> or DataSource
  • Migrations for schema changes

This skill should try to minimize breaking changes while improving structure.

Interaction with Other Skills

• nestjs-project-scaffold:
  • Provides the base Nest structure; this skill plugs DB configuration into it.
• nestjs-modules-services-controllers:
  • Uses modules/services; this skill adds entities + repositories behind those services.
• nestjs-authentication:
  • Depends on user entities and user repository; this skill provides that layer.
• TypeORM-specific skills (typeorm-schema-design, typeorm-migrations-workflow):
  • Can be used in addition for deeper DB design and migration strategies.

Example Prompts That Should Use This Skill

• “Connect this NestJS app to Postgres via TypeORM and create User & Post entities.”
• “Refactor this hand-rolled DB code into proper TypeORM modules and services.”
• “Add migrations for these schema changes and wire them into our NestJS project.”
• “Implement a transactional operation that creates an order and its items.”
• “Fix this TypeORM config; it works locally but fails in production.”

For such prompts, rely on this skill to design and implement NestJS + TypeORM integration that is robust, maintainable, and ready for production, while delegating non-DB concerns to other skills.