mongo-seeding-cli

library4.0.2jsnpmunverified

Mongo Seeding is a versatile tool designed for populating MongoDB databases, offering flexibility through its command-line interface (CLI), a programmatic JavaScript/TypeScript library, and a Docker image. It enables developers to define import data using JavaScript, TypeScript, or JSON files, allowing for dynamic data generation and logic, a key differentiator from simpler tools like `mongoimport` which primarily handle static JSON. The current stable version is 4.0.2, and the project demonstrates an active release cadence with regular maintenance updates and significant version bumps, such as v4.0.0. It is frequently used for setting up development environments, testing database queries, and establishing initial application states.

database

npm install mongo-seeding-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGO-SEEDING-CLI

mongo-seeding-cli

databasejavascriptv4.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Seeder

✓ import { Seeder } from 'mongo-seeding';

✗ const { Seeder } = require('mongo-seeding');

While CommonJS `require` is shown in older examples, modern Node.js and TypeScript projects should use ESM `import` for `mongo-seeding` v3+ for better compatibility and type inference.

SeederConfig

✓ import type { SeederConfig } from 'mongo-seeding';

✗ import { SeederConfig } from 'mongo-seeding';

Import `SeederConfig` as a type for configuration interfaces, primarily used with TypeScript for type checking.

Transformers

✓ import { Seeder } from 'mongo-seeding'; const { replaceDocumentIdWithUnderscoreId, setTimestamps } = Seeder.Transformers;

✗ import { Transformers } from 'mongo-seeding';

Utility transformers are exposed as static properties on the `Seeder` class, not as top-level named exports.

This quickstart demonstrates how to programmatically seed a MongoDB database using the `mongo-seeding` library in TypeScript, including configuring the seeder, reading data from files, and applying transformers. It also highlights the usage of `bulkWriteOptions` introduced in v4.0.0.

import { Seeder } from 'mongo-seeding'; import path from 'path'; const config = { database: 'mongodb://localhost:27017/my-database-test', dropDatabase: true, // Be cautious: this will delete the entire database dropCollections: true, // As of v4.0.0, use bulkWriteOptions instead of collectionInsertManyOptions bulkWriteOptions: { ordered: false, }, }; const seeder = new Seeder(config); const collections = seeder.readCollectionsFromPath( path.resolve(__dirname, './data'), { transformers: [Seeder.Transformers.replaceDocumentIdWithUnderscoreId], }, ); async function seedDatabase() { try { console.log('Starting database seeding...'); await seeder.import(collections); console.log('Database seeding completed successfully.'); } catch (err) { console.error('Database seeding failed:', err); process.exit(1); } } // Example data structure in a './data/users/users.js' file: // module.exports = [ // { id: 'user1', name: 'Alice', email: 'alice@example.com' }, // { id: 'user2', name: 'Bob', email: 'bob@example.com' }, // ]; seedDatabase();

mongo-seed --version

Debug

Known issues

breakingIn `mongo-seeding` v4.0.0, the `collectionInsertManyOptions` property in `SeederConfig` was replaced by `bulkWriteOptions`. This change aligns with updates in the underlying MongoDB driver API.

fix

Update your `SeederConfig` to use `bulkWriteOptions` instead of `collectionInsertManyOptions`. For example, `{ bulkWriteOptions: { ordered: false } }`.

affects: >=4.0.0

gotchaThe `mongo-seeding` library and CLI periodically update their supported Node.js versions. For example, v3.7.1 updated to Node 16, and v4.0.2 updated to Node 22.15. Using an older Node.js runtime with newer package versions may lead to compatibility issues or errors.

fix

Ensure your Node.js environment meets the minimum requirements specified in the package's `package.json` or release notes. Consider using `nvm` or a similar tool to manage Node.js versions.

affects: >=3.7.1

gotchaFor TypeScript data import files, ensure proper configuration for `ts-node` or a similar transpiler if running directly, or pre-transpile the files. The `--transpile-only` CLI option can improve performance by skipping type checking.

fix

If encountering issues with TypeScript data files, add `ts-node` to your project and register it, or use the `--transpile-only` flag with the CLI: `DEBUG=mongo-seeding npx ts-node your-seed-script.ts` or `seed --transpile-only ./data`.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'collectionInsertManyOptions') or Property 'collectionInsertManyOptions' does not exist on type 'SeederConfig'.

Attempting to use `collectionInsertManyOptions` in `SeederConfig` after upgrading to `mongo-seeding` v4.x.

fix

Replace `collectionInsertManyOptions` with `bulkWriteOptions` in your `SeederConfig` object.

SyntaxError: Cannot use import statement outside a module or ReferenceError: require is not defined

Mixing CommonJS `require()` with ESM `import` statements in Node.js, or trying to use ESM syntax in a non-ESM context (e.g., a `.js` file without `"type": "module"` in `package.json`).

fix

For programmatic use, ensure your project is configured for ESM (add `"type": "module"` to `package.json`) and use `import` statements. If using CommonJS, stick to `require()` and ensure the library version supports it, or use a transpiler.

MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017 or Unable to connect to MongoDB

The MongoDB server is not running, is configured on a different host/port, or network issues are preventing a connection.

fix

Verify that your MongoDB instance is running and accessible. Check the connection URI/details (host, port, credentials) in your `SeederConfig` or CLI parameters (e.g., `--db-uri`). Ensure no firewall is blocking the connection. Run `docker run --rm -p 27017:27017 mongo` for a quick local MongoDB instance.

Error: Path to collections is not specified or Error: No collections found in the specified path

The path provided to `seeder.readCollectionsFromPath()` is incorrect, empty, or the data files within do not follow the expected structure (e.g., subdirectories for collections, JS/JSON files exporting data).

fix

Double-check the `path.resolve()` argument. Ensure your data directory has subdirectories named after your collections (e.g., `./data/users/user-data.js`) and each file exports an array or object of documents.

Upgrade

Version history

4.0.2latest on npm

Audit

Dependencies

mongo-seedingrequiredThe `mongo-seeding-cli` package is a command-line interface wrapper for the `mongo-seeding` core library, leveraging its programmatic capabilities.

mongodbrequiredThe `mongo-seeding` library directly interacts with MongoDB using the official Node.js driver.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/pkosiec/mongo-seeding ↗

packagehttps://www.npmjs.com/package/mongo-seeding-cli ↗

homepagehttps://www.mongo-seeding.com/ ↗