npm package: @saalim192/seedforge
Description: Schema-aware Prisma seed generator
Author: Saalim Aqueel
Latest version: 1.0.1

# SeedForge

Schema-aware Prisma seed generator.

SeedForge reads `schema.prisma`, analyzes models and relations, and generates a working `prisma/seed.ts`. It is built for development workflows where schemas change often and seed scripts become expensive to maintain by hand.

## Why

Manual Prisma seeds usually drift in the same places:

- required fields change
- relation order breaks
- new models are missed
- local environments stop matching each other

SeedForge generates deterministic relational seed code from the schema instead of relying on a hand-maintained seed file.

## What it does

- Parses Prisma schema metadata with DMMF
- Builds a dependency graph from model relations
- Orders inserts to satisfy foreign keys
- Generates deterministic values for required scalars, enums, and scalar lists
- Supports model-level `count`, `perParent`, and `disabled` config
- Generates Prisma 7-compatible Postgres seeds using `@prisma/adapter-pg`
- Makes generated seeds idempotent by clearing existing data in reverse dependency order

Example dependency chain:

```text
Category -> Product -> ProductVariant
Customer -> Order -> OrderItem -> Payment
```

## Install

```bash
npm install -D seedforge
```

## Quick start

1. Generate a seed:

```bash
npx seedforge generate
```

2. Generate the Prisma client:

```bash
npx prisma generate
```

3. Run the seed:

```bash
npx prisma db seed
```

Recommended workflow after schema changes:

```bash
npx prisma migrate dev
npx seedforge generate --force
npx prisma generate
npx prisma db seed
```

## Prisma 7 setup

SeedForge supports Prisma 7-style config-driven datasource URLs.

Example `prisma.config.ts`:

```ts
import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
    seed: "tsx prisma/seed.ts",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});
```

Example datasource block in `prisma/schema.prisma`:

```prisma
datasource db {
  provider = "postgresql"
}
```

For Prisma 7 Postgres projects, generated seeds initialize Prisma Client with `@prisma/adapter-pg`.

## Commands

### `seedforge generate`

Generate `prisma/seed.ts` from the current schema.

Useful flags:

- `--schema <path>`: custom schema path
- `--output <path>`: custom output file
- `--dry-run`: print generated seed without writing
- `--force`: overwrite an existing file

### `seedforge init`

Create `seedforge.config.ts`.

### `seedforge doctor`

Validate schema loading and dependency ordering.

### `seedforge visualize`

Print an ASCII dependency graph.

### `seedforge clean`

Remove the generated seed file.

## Configuration

Create `seedforge.config.ts` in the project root:

```ts
export default {
  global: {
    count: 5,
  },
  models: {
    Category: { count: 6 },
    Product: { perParent: 8 },
    ProductVariant: { perParent: 3 },
    Payment: { disabled: true },
  },
};
```

Rules:

- `count`: total records for a model
- `perParent`: records created per required parent relation
- `disabled`: skip a model entirely

## Generated seed behavior

Generated seeds are deterministic for the same schema and config. That makes them easier to diff, rerun, and debug.

The generated file:

- imports Prisma Client
- clears existing records in reverse dependency order
- creates parent models before children
- reuses created record IDs for required foreign keys
- emits enum values from the schema
- emits scalar lists when required

## Supported scope

Works best for development seeding on relational Prisma schemas, especially:

- ecommerce apps
- SaaS products
- dashboards and admin tools
- content systems

Databases:

- PostgreSQL
- MySQL
- SQLite
- CockroachDB
- MongoDB support is best-effort at schema parsing level

## Limits

SeedForge generates valid scaffolding, not domain-perfect fixture data.

You may still want to customize:

- business-specific enums and statuses
- auth-sensitive fields
- highly constrained unique data
- special relation strategies for edge-case schemas

## Local development

```bash
npm install
npm run build
npm run dev -- generate --dry-run
```

## Examples

See [examples/README.md](/home/shxdow/Projects/seedforge/examples/README.md) for sample schemas and configs.

## License

MIT