serverless-dynamodb-seeder

A lightweight Serverless Framework plugin that focuses exclusively on seeding DynamoDB tables. It is built to work seamlessly with serverless-localstack, custom endpoints (e.g. LocalStack edge, AWS endpoints, localhost), and regular AWS accounts.

Requirements

• Node.js 22 or newer
• Serverless Framework v3+

Installation

npm install --save-dev serverless-dynamodb-seeder

serverless.yml:

plugins:
  - serverless-dynamodb-seeder

Configuration

Declare the tables you want to seed in custom.dynamodb.seed. Categories let you group seed files so that you can run subsets from the CLI. If you set custom.dynamodb.start.migrate: true (or pass --migrate to the seed command) the plugin will create any missing tables based on your CloudFormation resources before it starts writing data.

custom:
  # Optional stage allow-list. When omitted, seeding runs in every stage.
  dynamodb:
    stages:
      - local
      - test

    # Optional global defaults. You can also pass these via CLI flags.
    region: us-east-1
    convertEmptyValues: true

    # Local start helpers (used by "serverless offline")
    start:
      migrate: true   # create missing tables before seeding
      seed: true      # run the seeder automatically on offline start

    # Seed definitions grouped by category
    seed:
      demo:
        sources:
          - table: Users
            sources:
              - seeds/users.json
          - table: RawUsers
            rawsources:
              - seeds/raw-users.json
      smoke:
        sources:
          - table: Subscriptions
            sources:
              - seeds/subscriptions.json

Each entry supports:

• table (required) – DynamoDB table name.
• sources – JSON files containing plain JavaScript objects (DocumentClient format).
• rawsources – JSON files using the low-level AttributeValue format.

Paths are resolved relative to your Serverless service directory.

LocalStack integration

When custom.localstack is present the plugin automatically reuses its endpoint information. Fallback order:

1. CLI --endpoint
2. custom.dynamodb.endpoint
3. custom.localstack.endpoints.dynamodb (or DynamoDB)
4. custom.localstack.host + edgePort
5. Environment variables (DYNAMODB_SEED_ENDPOINT, DYNAMODB_ENDPOINT, LOCALSTACK_HOST*)
6. http://localhost:4566

This makes it compatible with serverless-localstack without additional configuration.

Usage

sls dynamodb seed

CLI options:

• --seed / -s – Comma-separated list of categories to execute.
• --migrate – Create DynamoDB tables before seeding (defaults to custom.dynamodb.start.migrate).
• --endpoint / -e – Override the DynamoDB endpoint.
• --region / -r – Override the region used when creating the client.
• --convertEmptyValues – Enable DocumentClient empty value conversion.

Example:

sls dynamodb seed --seed=demo --endpoint=http://localhost:4566

When you run sls offline start, the plugin reads custom.dynamodb.start to decide whether to create tables (start.migrate) and/or seed data (start.seed).

Seed file examples

seeds/users.json

[
  {
    "id": "1",
    "name": "Alice",
    "tags": ["local"]
  }
]

seeds/raw-users.json

[
  {
    "id": { "S": "1" },
    "score": { "N": "10" }
  }
]

Testing

npm test

The test suite stubs the AWS SDK so it runs without a local DynamoDB process.

npm run lint

Run ESLint to keep the codebase consistent.

License

MIT