Skip to content

shopwareLabs/shopware-catalog-generator

BranchesTags

Repository files navigation

Shopware Catalog Generator

Generate AI-powered demo catalogs for Shopware. Creates SalesChannels with category trees, products, descriptions, images, reviews, variants, CMS pages, cross-selling, demo customers, promotions, and themed storefronts (AI-generated brand colors, logo, favicon).

Architecture details: See CONCEPTS.md for diagrams and in-depth explanations.

Quick Start

bun install
bun run build

Create a .env file:

# AI Provider — pick one:
AI_PROVIDER=github-models               # Free with GitHub Copilot
AI_API_KEY=ghp_your_github_token        # github.com/settings/tokens
# AI_PROVIDER=pollinations              # Alternative: enter.pollinations.ai
# AI_API_KEY=sk_your_pollinations_key

# Shopware connection (required to sync data)
SW_ENV_URL=http://localhost:8000
SW_CLIENT_ID=your-access-key-id      # Settings → System → Integrations
SW_CLIENT_SECRET=your-secret-key     # Settings → System → Integrations

The SW_CLIENT_ID and SW_CLIENT_SECRET authenticate against the Shopware Admin API. Create an integration in your Shopware Admin under Settings → System → Integrations, then copy the Access key ID and Secret access key into your .env.

Generate a full catalog:

bun run generate --name=music --description="Musical instruments and accessories for musicians of all levels"

This creates a SalesChannel named "music" with 3 top-level categories, ~90 products, AI-generated descriptions, properties, and optional images.

Catalog Templates

Pre-generated, ready-to-use catalogs are available at shopware-catalog-templates. Currently included: music, garden, and beauty.

When you run generate, the CLI automatically checks if a matching template exists. If found, it skips AI generation entirely and uploads the template directly:

# Uses a pre-generated template (instant, no AI needed)
bun run generate --name=music

# Force AI generation even if a template exists
bun run generate --name=music --no-template

Templates require git access via SSH keys or credential helper.

Maintaining the Templates Repository

When regenerating all templates, squash the history to keep the repo size small. A maintenance script is included for this:

bash scripts/reset-templates-history.sh /path/to/shopware-catalog-templates

This creates a fresh single commit, cleans up all stale refs, and repackages the objects to the minimum possible size. Afterwards, a force-push is required.

AI Providers & Performance

Provider API Key Text Images Best For
github-models PAT Free Free (Pollinations) Free with GitHub Copilot
pollinations sk_* Parallel Parallel (with key) Fast, no rate limits
pollinations pk_* Sequential Free (pollen preserved) Free tier
openai sk-... Parallel Paid (gpt-image-1) Production, high volume

Free Setup (GitHub Copilot)

If you have a GitHub Copilot subscription, you can generate catalogs entirely for free — text via GitHub Models, images via Pollinations free tier:

AI_PROVIDER=github-models
AI_API_KEY=ghp_your_github_token

No IMAGE_PROVIDER or IMAGE_API_KEY needed. Images are automatically generated via Pollinations free tier.

Create a personal access token at github.com/settings/tokens (no extra scopes needed beyond Copilot access).

Other Providers

# Pollinations with secret key - parallel processing, no rate limits
AI_PROVIDER=pollinations
AI_API_KEY=sk_your_pollinations_secret_key

# Pollinations with publishable key - pollen preserved for text, images are free
AI_PROVIDER=pollinations
AI_API_KEY=pk_your_pollinations_key

# OpenAI (full parallel processing, paid images)
AI_PROVIDER=openai
AI_API_KEY=sk-your-openai-key

Get a Pollinations API key at enter.pollinations.ai

Optional settings:

AI_MODEL=gpt-4o              # Override text model
IMAGE_PROVIDER=none          # Disable images
IMAGE_MODEL=gpt-image-1-mini # OpenAI default; or gpt-image-1.5, flux, turbo, klein
IMAGE_QUALITY=low            # OpenAI only: low (fastest), medium, high, auto

Expected Times (90 products)

Text generation only (blueprint hydration):

Provider Processing Time
OpenAI Parallel (5x) ~5 min
Pollinations (sk_*) Parallel (5x) ~5 min
GitHub Models Limited (2x) ~10 min
Pollinations (pk_*) Sequential ~13 min

Full generation with images (~270 images at 3 views per product):

Provider Image Model Quality Time
OpenAI gpt-image-1-mini low ~8-12 min
OpenAI gpt-image-1-mini medium ~12-18 min
OpenAI gpt-image-1.5 medium ~20-25 min
Pollinations flux (default) - ~15-20 min
Pollinations turbo (fast) - ~10-15 min
Any (images: none) - - ~5-13 min

Image generation is the primary time factor. Use IMAGE_PROVIDER=none to skip images for faster testing.

Shopware Connection

SW_ENV_URL=http://localhost:8000
SW_CLIENT_ID=your-access-key-id
SW_CLIENT_SECRET=your-secret-key

To create integration credentials:

  1. Open Shopware Admin → Settings → System → Integrations
  2. Click Add integration
  3. Copy the Access key ID → SW_CLIENT_ID
  4. Copy the Secret access key → SW_CLIENT_SECRET

Domains & Languages

Every generated SalesChannel automatically gets two domains:

Domain Language Currency
{name}.localhost:8000 English USD
{name}-de.localhost:8000 German EUR

The German domain is only created if de-DE language and its snippet set are installed in Shopware. If not, a warning is logged and only the English domain is created.

To install German: Settings → Shop → Languages → Add language → German.

CLI Usage

For the complete reference with all flags and options, see CLI Reference.

Generate

bun run generate --name=music --description="Musical instruments and accessories for musicians of all levels"

Blueprint Workflow

For more control, run the 3-phase pipeline separately. See CONCEPTS.md for details.

bun run blueprint create --name=music --description="Musical instruments and accessories"
bun run blueprint hydrate --name=music
bun run generate --name=music

Post-Processors

Run specific post-processors after upload:

bun run process --name=music --only=images,reviews

Cleanup

bun run cleanup -- --salesChannel="music"                    # Products + categories
bun run cleanup -- --salesChannel="music" --full --delete    # Everything

Cache Management

bun run cache:list                    # Show cached SalesChannels
bun run cache:clear -- music          # Move to trash
bun run cache:restore -- --all        # Restore from trash

Post-Processors

Post-processors run after upload for resource-intensive tasks (images, reviews, CMS pages, etc.).

Processor Description Dependencies
cms-home Homepage layout with product listing none
cms-text Text elements demo page none
cms-images Image elements demo page none
cms-video Video elements demo page none
cms-text-images Text & Images demo page none
cms-commerce Commerce elements demo page images
cms-form Form elements demo page none
cms-footer-pages Shared footer and legal pages none
cross-selling Category-based cross-selling via product streams none
customers Demo customer accounts with B2B group none
images Upload pre-generated product/category images none
manufacturers Fictional manufacturer creation none
promotions Tiered pricing and promotion codes none
reviews Product reviews (0-10 per product) none
theme Child theme with brand colors, logo, favicon none
variants Variant product creation manufacturers
digital-product Digital product (Gift Card) none
cms-testing Testing category hierarchy cms-*, digital-product

Processors run in parallel when possible, respecting dependency order. See CONCEPTS.md for the execution diagram.

Server Mode

Run as an HTTP service with background processing:

bun run server
Method Endpoint Description
POST /generate Start generation (returns process ID)
GET /status/:id Poll process status, progress, and logs
GET /health Health check and active process count 
curl -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{"envPath":"http://localhost:8000","salesChannel":"music","description":"Musical instruments"}'

See CLI Reference for all request fields.

MCP Server (AI Assistant Integration)

This project includes an MCP server for AI assistant integration in Cursor IDE. All CLI commands are exposed as auto-discoverable tools.

Setup

The MCP config at .cursor/mcp.json uses /bin/sh to resolve $HOME dynamically:

{
    "mcpServers": {
        "catalog-generator": {
            "command": "/bin/sh",
            "args": ["-c", "\"$HOME/.bun/bin/bun\" run src/mcp/index.ts"]
        }
    }
}

If your bun is installed elsewhere, adjust the path accordingly.

Testing

bun run mcp:dev       # Interactive terminal testing
bun run mcp:inspect   # Web UI inspector

Contributing

Development

bun run dev           # Watch mode
bun run lint          # Lint + typecheck (oxlint + tsc)
bun run format        # Format code (oxfmt)
bun run build         # Build (lint + format + bundle)

Testing

bun test              # Run all tests
bun test --watch      # Watch mode
bun test --coverage   # With coverage report

E2E Testing

./test-e2e.sh                              # Full: create → hydrate → upload → verify
./test-e2e.sh --reuse=music                # Reuse existing blueprint
./test-e2e.sh --reuse=music --skip-hydrate # Skip AI, just upload
./test-e2e.sh --cleanup=music              # Cleanup only
bun run test:verify --name=music           # Verify Shopware data

Extending

See AGENTS.md for developer documentation on adding post-processors, AI providers, CMS fixtures, and CLI commands.

License

This project is licensed under the GNU Affero General Public License v3.0 or later.

About

TypeScript based Catalog Genertor using Bun and our official API Client

Resources

Readme

License

AGPL-3.0 license
Activity
Custom properties

Stars

7 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages