{"id":17296,"library":"mongo-seeding-cli","title":"Mongo Seeding CLI and Library","description":"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.","status":"active","version":"4.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/pkosiec/mongo-seeding","tags":["javascript","mongo","mongodb","seed","db-seed","database","seeding","db","cli"],"install":[{"cmd":"npm install mongo-seeding-cli","lang":"bash","label":"npm"},{"cmd":"yarn add mongo-seeding-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add mongo-seeding-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The `mongo-seeding-cli` package is a command-line interface wrapper for the `mongo-seeding` core library, leveraging its programmatic capabilities.","package":"mongo-seeding","optional":false},{"reason":"The `mongo-seeding` library directly interacts with MongoDB using the official Node.js driver.","package":"mongodb","optional":false}],"imports":[{"note":"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.","wrong":"const { Seeder } = require('mongo-seeding');","symbol":"Seeder","correct":"import { Seeder } from 'mongo-seeding';"},{"note":"Import `SeederConfig` as a type for configuration interfaces, primarily used with TypeScript for type checking.","wrong":"import { SeederConfig } from 'mongo-seeding';","symbol":"SeederConfig","correct":"import type { SeederConfig } from 'mongo-seeding';"},{"note":"Utility transformers are exposed as static properties on the `Seeder` class, not as top-level named exports.","wrong":"import { Transformers } from 'mongo-seeding';","symbol":"Transformers","correct":"import { Seeder } from 'mongo-seeding'; const { replaceDocumentIdWithUnderscoreId, setTimestamps } = Seeder.Transformers;"}],"quickstart":{"code":"import { Seeder } from 'mongo-seeding';\nimport path from 'path';\n\nconst config = {\n  database: 'mongodb://localhost:27017/my-database-test',\n  dropDatabase: true, // Be cautious: this will delete the entire database\n  dropCollections: true,\n  // As of v4.0.0, use bulkWriteOptions instead of collectionInsertManyOptions\n  bulkWriteOptions: {\n    ordered: false,\n  },\n};\n\nconst seeder = new Seeder(config);\nconst collections = seeder.readCollectionsFromPath(\n  path.resolve(__dirname, './data'),\n  {\n    transformers: [Seeder.Transformers.replaceDocumentIdWithUnderscoreId],\n  },\n);\n\nasync function seedDatabase() {\n  try {\n    console.log('Starting database seeding...');\n    await seeder.import(collections);\n    console.log('Database seeding completed successfully.');\n  } catch (err) {\n    console.error('Database seeding failed:', err);\n    process.exit(1);\n  }\n}\n\n// Example data structure in a './data/users/users.js' file:\n// module.exports = [\n//   { id: 'user1', name: 'Alice', email: 'alice@example.com' },\n//   { id: 'user2', name: 'Bob', email: 'bob@example.com' },\n// ];\n\nseedDatabase();","lang":"typescript","description":"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."},"warnings":[{"fix":"Update your `SeederConfig` to use `bulkWriteOptions` instead of `collectionInsertManyOptions`. For example, `{ bulkWriteOptions: { ordered: false } }`.","message":"In `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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=3.7.1"},{"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`.","message":"For 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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Replace `collectionInsertManyOptions` with `bulkWriteOptions` in your `SeederConfig` object.","cause":"Attempting to use `collectionInsertManyOptions` in `SeederConfig` after upgrading to `mongo-seeding` v4.x.","error":"TypeError: Cannot read properties of undefined (reading 'collectionInsertManyOptions') or Property 'collectionInsertManyOptions' does not exist on type 'SeederConfig'."},{"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.","cause":"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`).","error":"SyntaxError: Cannot use import statement outside a module or ReferenceError: require is not defined"},{"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.","cause":"The MongoDB server is not running, is configured on a different host/port, or network issues are preventing a connection.","error":"MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017 or Unable to connect to MongoDB"},{"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.","cause":"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).","error":"Error: Path to collections is not specified or Error: No collections found in the specified path"}],"ecosystem":"npm","meta_description":null}