> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talosjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing seeds

> Scaffold a seed, implement run, and gate it by activity, environment, and dependencies.

A seed is a class implementing `ISeed`, registered with `@decorator.seed()`. The decorator adds the class to the container and to the seeds registry, so the runner can resolve, filter, and order it. `run()` populates the database, and the other members decide whether — and when — it runs.

## Scaffold a seed

Generate a seed with the CLI. `talos seed:create` writes a seed class under `modules/<module>/src/seeds/`, an accompanying `.yml` data file, and a matching test under `modules/<module>/tests/seeds/`, then regenerates the `seeds.ts` barrel export and creates the module's `bin/seed/run.ts` runner if it is missing.

```bash theme={null}
# Generate a seed in the shared module (prompts for the name)
talos seed:create

# Name the seed and target a module
talos seed:create --name=DemoUser --module=blog
```

| Option     | Description                                                      | Default             |
| ---------- | ---------------------------------------------------------------- | ------------------- |
| `--name`   | Name of the seed. Normalized to PascalCase with a `Seed` suffix. | Prompted if omitted |
| `--module` | Module the seed is created in.                                   | `shared`            |

The generated class loads its data from the sibling `.yml` file and is ready to fill in:

```typescript theme={null}
import { decorator, type Environment, type ISeed, type SeedClassType } from "@talosjs/seeds";
import data from "./demo-user-seed.yml";

@decorator.seed()
export class DemoUserSeed implements ISeed {
  public async run<T>(): Promise<T> {
    // Your seed logic here
    console.log(data);

    return data as T;
  }

  public isActive(): boolean {
    return true;
  }

  public async getDependencies(): Promise<SeedClassType[]> {
    return [];
  }

  public getEnv(): Environment[] {
    return [];
  }
}
```

See the [`seed:create` command](/cli/commands/seed-create) for the full reference.

## Implement `run()`

Fill in `run()` with the inserts that populate the database. Keep the records in the sibling `.yml` file and import them, so data stays separate from logic. Whatever `run()` returns is passed to any seed that depends on this one, so return the records a dependent seed needs to reference.

## Gate the seed

Three members decide whether the seed runs:

* **`isActive()`** — return `false` to skip the seed entirely. Use it to disable a seed without deleting it.
* **`getEnv()`** — return the environments the seed targets (for example `[Environment.Development, Environment.Test]`). An empty list runs in every environment; a non-empty list runs only when the current `APP_ENV` is included.
* **`getDependencies()`** — return the seed classes that must run first. Each dependency is resolved from the container and run before this seed, and its return value is passed into this seed's `run(data)`.

```typescript theme={null}
public getDependencies(): SeedClassType[] {
  return [UserSeed];
}

public getEnv(): Environment[] {
  return [Environment.Development, Environment.Test];
}
```

## Next steps

* [Running seeds](/seeds/running): populate the database with `talos seed:run`.
* [Caching](/seeds/caching): how a seed's run is cached and invalidated.