Skip to main content
The @talosjs/seeds package is a database seeding framework for populating initial data, fixtures, and test datasets. A seed is a class implementing ISeed with a run method, an active flag, an optional environment list, and an optional dependency list. Seeds are registered with a decorator, filtered by whether they are active and target the current environment, and run in dependency order.

​
How seeds behave

Each seed’s run() populates the database. A seed can gate itself with isActive() and restrict itself to specific environments with getEnv(), so the runner only executes seeds that apply to the current run. Seeds can also declare other seeds as dependencies, and those run first — their return values are passed into the dependent seed’s run(data), so a seed can build on the records its dependencies created. Unlike migrations, seeds have no database table recording what has run. The per-seed run cache is the only record that a seed already ran, letting seed:run skip a seed whose code is unchanged since its last successful run for the same environment.

​
The ISeed contract

A seed is a class that satisfies ISeed from @talosjs/seeds: 
export interface ISeed {
  run: <T = unknown>(data?: unknown[]) => Promise<T> | T;
  isActive: () => Promise<boolean> | boolean;
  getDependencies: () => Promise<SeedClassType[]> | SeedClassType[];
  getEnv: () => Promise<Environment[]> | Environment[];
}
MemberPurpose
run(data)Populate the database. Receives the return values of this seed’s dependencies as data.
isActive()Return false to skip the seed entirely; true to include it.
getDependencies()Return the seed classes that must run before this one.
getEnv()Restrict the seed to the listed environments. An empty list runs in every environment.

​
How seeds are selected

The runner resolves every registered seed from the container and keeps only those that apply to the run. A seed is skipped when isActive() returns false, or when getEnv() returns a non-empty list that does not include the current environment. The current environment comes from APP_ENV, which the seed:run command sets from its --env option.

​
Next steps

  • Writing seeds: scaffold a seed and implement run(), isActive(), getEnv(), and dependencies.
  • Running seeds: populate the database across every module with talos seed:run.
  • Caching: how the per-seed run cache skips unchanged seeds.