@ackplus/nest-seeder

📚 Documentation

👉 Full documentation & guides: ack-solutions.github.io/nest-seeder

| | | | --- | --- | | 🚀 Getting Started | 5-minute quickstart | | 🏭 Factories | Generate realistic data | | 🌱 Seeders | Insert & drop data | | 🖥️ CLI Reference | Every command & flag | | 📖 API Reference | Full API | | 🔀 Migration v1 → v2 | Upgrade guide | | 📝 Changelog | What changed |

✨ Features

• 🖥️ CLI-first — run nest-seed with zero changes to your app code. Auto-detects your config.
• 🏭 Factories + Faker.js — declare data with the @Factory decorator; supports dependent fields, inheritance, and overrides.
• 🔄 Any ORM — TypeORM, Mongoose, Prisma, or anything Nest can inject.
• 🎯 Selective & safe — run seeders by name, --refresh in foreign-key-safe order, or preview with --dry-run.
• 🛠️ Scaffolding — nest-seed init generates a config, factory, and seeder.
• 📦 Dual ESM + CJS with full TypeScript declarations.

📦 Installation

npm install @ackplus/nest-seeder @faker-js/faker
# For TypeScript config files:
npm install -D ts-node typescript

Requires Node 18+ and NestJS 10 or 11.

🚀 Quick Start

The fastest path is to scaffold the files:

npx nest-seed init

…or wire them up by hand:

1. Factory — src/database/factories/user.factory.ts

import { Factory } from '@ackplus/nest-seeder';

export class UserFactory {
  @Factory((faker) => faker.person.firstName())
  firstName: string;

  @Factory((faker) => faker.person.lastName())
  lastName: string;

  @Factory(
    (faker, ctx) => faker.internet.email({ firstName: ctx.firstName, lastName: ctx.lastName }).toLowerCase(),
    ['firstName', 'lastName'],
  )
  email: string;

  @Factory((faker) => faker.helpers.arrayElement(['admin', 'user', 'guest']))
  role: string;
}

2. Seeder — src/database/seeders/user.seeder.ts

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { Seeder, SeederName, DataFactory } from '@ackplus/nest-seeder';
import { User } from '../entities/user.entity';
import { UserFactory } from '../factories/user.factory';

@Injectable()
@SeederName('users')
export class UserSeeder implements Seeder {
  constructor(
    @InjectRepository(User) private readonly userRepository: Repository<User>,
  ) {}

  async seed(): Promise<void> {
    const factory = DataFactory.createForClass(UserFactory);
    const users = factory.generate(10);
    await this.userRepository.save(users);
  }

  async drop(): Promise<void> {
    await this.userRepository.createQueryBuilder().delete().execute();
  }
}

3. Config — seeder.config.ts (project root)

import { TypeOrmModule } from '@nestjs/typeorm';
import { defineSeederConfig } from '@ackplus/nest-seeder';
import { User } from './src/database/entities/user.entity';
import { UserSeeder } from './src/database/seeders/user.seeder';

export default defineSeederConfig({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: process.env.DB_HOST ?? 'localhost',
      port: Number(process.env.DB_PORT ?? 5432),
      username: process.env.DB_USERNAME ?? 'postgres',
      password: process.env.DB_PASSWORD ?? 'postgres',
      database: process.env.DB_DATABASE ?? 'app',
      entities: [User],
      synchronize: true,
    }),
    TypeOrmModule.forFeature([User]),
  ],
  seeders: [UserSeeder],
});

4. Run — add a script and go

{
  "scripts": {
    "seed": "nest-seed"
  }
}

npm run seed

That's it — the CLI auto-discovers seeder.config.ts and seeds your database. 🎉

🖥️ CLI at a glance

nest-seed                      # run all seeders (config auto-detected)
nest-seed --refresh            # drop (reverse order) then reseed
nest-seed --name users posts   # run only specific seeders
nest-seed --dry-run            # preview without writing
nest-seed list                 # list registered seeders
nest-seed init --orm mongoose  # scaffold starter files
nest-seed --help               # all options

See the full CLI reference.

🔀 Upgrading from v1?

v2 keeps the @Factory / Seeder / DataFactory core and modernizes the CLI, config, and packaging. Most apps upgrade in minutes — follow the Migration Guide.

🤝 Contributing

Contributions welcome! See the Contributing Guide.

📄 License

MIT © AckPlus

Built with NestJS · Powered by Faker.js