@strivio/prisma-seeds

Database seeding framework for Prisma with JSON-based data loading.

Quick Start

# Populate database
yarn nx run api:db:seed

# Reset and re-populate
yarn nx run api:db:reset

Documentation

📖 Full documentation: docs/infrastructure/prisma-seeds.md

Topics covered:

• JSON-based seeding architecture
• Validation and schema definitions
• Multi-language support
• Asset management
• Relationship handling

Development

# Build
yarn nx build prisma-seeds

# Test
yarn nx test prisma-seeds

# Lint
yarn nx lint prisma-seeds

Project Structure

libs/backend/features/[feature]/
├── seed.config.mjs         # Configuration
└── .seed/
    ├── data/               # JSON content files
    │   └── items.json
    ├── schemas/            # Validation rules (optional)
    │   └── item.schema.json
    └── assets/             # Images and media
        └── images/

Example: Products

Data File (.seed/data/products.json):

{
  "products": [
    {
      "id": "prod-001",
      "name": {
        "en": "Protein Powder",
        "de": "Protein Pulver"
      },
      "price": 49.99,
      "category": "supplements",
      "image": "@asset:protein-powder"
    }
  ]
}

Result:

• Product created in database
• Name available in English and German
• Image uploaded to cloud storage
• Linked to supplements category

Documentation

Complete guides available in /docs/seeding/:

Getting Started

• Getting Started - Create your first seed configuration
• JSON Seeding - Structure your JSON data files

Features

• Asset Management - Handle images and media
• Localization - Multi-language content

Best Practices

• Best Practices - Patterns and conventions
• Examples - Real-world implementations

Common Use Cases

Initial Setup

Populate database with essential data:

• User authentication
• Categories and tags
• Reference data

Content Updates

Deploy new or updated content:

• New exercises
• Updated recipes
• Fresh tips

Development

Create test data:

• Sample users
• Example workouts
• Test products

Configuration

Each feature defines its own seeding:

Basic Configuration:

• name - Feature identifier
• order - When to run (1-100)
• dependencies - Required features
• data - JSON file paths
• assets - Image configuration

Processing Options:

• validation - Schema checking
• updates - Create vs update logic
• relationships - Link to other entities

Entity Resolution

Automatically find and link related data:

Example:

{
  "exercise": {
    "name": "Bench Press",
    "category": "barbell",
    "muscles": ["chest", "triceps"]
  }
}

System will:

1. Find "barbell" category by name
2. Find "chest" and "triceps" muscles
3. Create proper database links

Localization

Support multiple languages:

JSON Format:

{
  "name": {
    "en": "Bench Press",
    "de": "Bankdrücken"
  }
}

Database Storage:

• Primary language (EN) for search
• All translations in separate table
• Fallback to English if missing

Asset Management

Upload images automatically:

JSON Reference:

{
  "image": "@asset:bench-press"
}

Process:

1. Find image file in .seed/assets/
2. Optimize (resize, format conversion)
3. Upload to cloud storage (Vercel Blob)
4. Store URL in database

Performance

Optimized Processing:

• Auto-caching prevents duplicate queries
• Batch processing for efficiency
• Transaction support for consistency

Example:

• 540 exercises processed in ~4 minutes
• Single query loads all categories (cached)
• No N+1 query problems

CLI Commands

# Seed everything
yarn nx run api:db:seed

# Reset and re-seed
yarn nx run api:db:reset

# Seed specific feature
yarn nx run api:db:seed --feature=fit

Troubleshooting

Validation Errors

Check JSON structure matches schema.

Missing References

Ensure related entities seeded first (check order/dependencies).

Asset Upload Fails

Verify Vercel Blob token and network connection.

Duplicate Entries

Check unique field configuration and existing data.

Development

Adding New Features

1. Create .seed/ directory in feature
2. Add JSON data files
3. Create seed.config.mjs
4. Test locally
5. Commit and deploy

Updating Content

1. Edit JSON files
2. Run seeding locally
3. Verify changes
4. Commit updates
5. Deploy to production

Testing

# Test with fresh database
yarn nx run api:db:reset
yarn nx run api:db:seed

# Validate JSON
cat .seed/data/items.json | jq .

Architecture

Modular Design:

• Each feature owns its data
• Clear dependencies
• Isolated testing
• Easy to extend

Type-Safe:

• TypeScript throughout
• Prisma type generation
• Validation schemas

Production-Ready:

• Error handling
• Logging
• Performance optimized
• Tested at scale

Support

For questions or issues:

• Check /docs/seeding/ documentation
• Review example implementations
• See feature-specific READMEs

Version: 2.0 Updated: January 2025