Saleor Configurator

Commerce as Code — Define your Saleor store in YAML, sync with your instance

Declarative configuration management for Saleor e-commerce stores.

What is Saleor Configurator?

Saleor Configurator brings infrastructure-as-code principles to e-commerce. Instead of manually configuring your store through the dashboard, you define everything in version-controlled YAML files and sync them to your Saleor instance.

Key Benefits:

• Version Control — Track all store changes in Git with full history
• Reproducibility — Spin up identical configurations across environments
• Multi-Environment — Manage dev, staging, and production from the same codebase
• Review Process — Use pull requests to review configuration changes
• Automation — Integrate with CI/CD for automated deployments

┌─────────────┐     introspect     ┌─────────────┐
│   Saleor    │ ─────────────────► │  config.yml │
│  Instance   │                    │   (local)   │
└─────────────┘                    └─────────────┘
       ▲                                  │
       │                                  │
       │         deploy                   │ modify
       └──────────────────────────────────┘

Quick Start

Prerequisites: Node.js 20+

Installation

# Run directly (recommended)
npx @saleor/configurator start
pnpm dlx @saleor/configurator start

# Or install globally
npm install -g @saleor/configurator
pnpm add -g @saleor/configurator

Getting Your API Token

Before using Saleor Configurator, you need an API token from your Saleor instance. This token allows the CLI to read and modify your store configuration.

Step 1: Access Your Saleor Dashboard

Go to your Saleor Dashboard:

• Saleor Cloud: https://your-store.saleor.cloud/dashboard/
• Self-hosted: https://your-domain.com/dashboard/

Step 2: Create a New App

1. Navigate to Extensions → Installed in the sidebar
2. Click Add Extension → Provide details manually
3. Enter a name like Configurator or Configuration Manager

Step 3: Assign Permissions

Grant the app all permissions needed for configuration management:

Permission Category	Required For
Products	Product types, categories, products, variants
Channels	Sales channels, currency settings
Shipping	Shipping zones, methods, warehouses
Pages	Page types (model types), pages (models)
Menus	Navigation structures
Discounts	Vouchers and sales (if using)
Settings	Shop settings, tax configuration

Tip: For full configuration management, select all available permissions. You can restrict permissions later for specific environments.

Step 4: Generate the Token

1. After creating the app, go to the app's detail page
2. Find the Tokens section
3. Click Create Token
4. Copy the token immediately — it won't be shown again

Your token will look like: eyJhbGciOiJSUzI1NiIsInR5cCI6... (JWT format) or a shorter alphanumeric string.

Step 5: Store Your Credentials

For repeated use, store your credentials as environment variables:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export SALEOR_URL="https://your-store.saleor.cloud/graphql/"
export SALEOR_TOKEN="your-token-here"

# Then use in commands
npx @saleor/configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN

Security Note: Never commit tokens to version control. Use environment variables or a secrets manager.

Verify Your Setup

Test that your token works:

npx @saleor/configurator introspect --url=$SALEOR_URL --token=$SALEOR_TOKEN --include shop

If successful, you'll see your shop settings downloaded. If you get an authentication error, verify your token and URL (ensure the URL ends with /graphql/).

First-Time Setup

The easiest way to get started is with the interactive wizard:

npx @saleor/configurator start

Core Workflow

# 1. Download your current store configuration
npx @saleor/configurator introspect \
  --url https://your-store.saleor.cloud/graphql/ \
  --token your-app-token

# 2. Modify config.yml to define your desired state

# 3. Preview changes before applying
npx @saleor/configurator diff \
  --url https://your-store.saleor.cloud/graphql/ \
  --token your-app-token

# 4. Deploy your configuration
npx @saleor/configurator deploy \
  --url https://your-store.saleor.cloud/graphql/ \
  --token your-app-token

Need a token? See Getting Your API Token above for step-by-step instructions.

Quick Reference

Task	Command
Download config	npx @saleor/configurator introspect --url <URL> --token <TOKEN>
Preview changes	npx @saleor/configurator diff --url <URL> --token <TOKEN>
Deploy changes	npx @saleor/configurator deploy --url <URL> --token <TOKEN>
Apply recipe	npx @saleor/configurator recipe apply <name> --url <URL> --token <TOKEN>
CI deployment	npx @saleor/configurator deploy --url <URL> --token <TOKEN> --ci

Commands

All commands support --help for detailed usage information.

start — Interactive Wizard

Guided setup for exploring features and connecting to your Saleor instance.

npx @saleor/configurator start

introspect — Download Remote Config

Fetches the current configuration from your Saleor instance and saves it locally.

npx @saleor/configurator introspect --url <URL> --token <TOKEN>

# With custom output file
npx @saleor/configurator introspect --url <URL> --token <TOKEN> --config production.yml

diff — Preview Changes

Shows what would change if you deployed, without making any modifications.

npx @saleor/configurator diff --url <URL> --token <TOKEN>

deploy — Apply Configuration

Syncs your local configuration to the remote Saleor instance.

# Interactive mode with confirmation prompts
npx @saleor/configurator deploy --url <URL> --token <TOKEN>

# CI mode - skip confirmations
npx @saleor/configurator deploy --url <URL> --token <TOKEN> --ci

# Custom config file
npx @saleor/configurator deploy --url <URL> --token <TOKEN> --config production.yml

recipe — Pre-Built Templates

Apply ready-to-use configuration templates for common e-commerce scenarios.

# List available recipes
npx @saleor/configurator recipe list

# Preview a recipe's configuration
npx @saleor/configurator recipe show multi-region

# Apply a recipe to your instance
npx @saleor/configurator recipe apply multi-region --url <URL> --token <TOKEN>

# Export for customization
npx @saleor/configurator recipe export multi-region --output my-config.yml

Configuration

Define your store configuration in YAML (default: config.yml).

Structure Overview

# Global store settings
shop:
  defaultMailSenderName: "My Store"
  displayGrossPrices: true

# Sales channels (multi-currency, multi-region)
channels:
  - name: "United States"
    slug: us
    currencyCode: USD
    defaultCountry: US

# Product catalog structure
productTypes:
  - name: "Book"
    isShippingRequired: true
    productAttributes:
      - name: "Author"
        inputType: PLAIN_TEXT

categories:
  - name: "Fiction"
    slug: fiction
    subcategories:
      - name: "Fantasy"
        slug: fantasy

products:
  - name: "Sample Book"
    slug: sample-book
    productType: "Book"
    category: fiction
    variants:
      - name: "Hardcover"
        sku: "BOOK-001"

# Fulfillment
warehouses:
  - name: "Main Warehouse"
    slug: main-warehouse
    address:
      streetAddress1: "123 Commerce St"
      city: "New York"
      country: US

shippingZones:
  - name: "US Zone"
    countries: ["US"]
    warehouses: ["main-warehouse"]

Domain Modeling

Saleor's domain model consists of interconnected entity types that you can configure declaratively.

Core Entities

Entity	Purpose	Configured Via
Products	Sellable items with variants, pricing, stock	products
Product Types	Templates defining product structure and attributes	productTypes
Categories	Hierarchical product taxonomy (one category per product)	categories
Collections	Flexible product groupings for merchandising	collections
Models	Custom entities extending beyond products (e.g., Brands, Ingredients)	models
Model Types	Templates defining model structure	pageTypes
Structures	Hierarchical navigation linking categories, collections, models, URLs	menus

Attributes

Attributes are reusable typed fields assigned to products or models:

Type	Description	Example
DROPDOWN	Single-select from predefined values	Color: Red, Blue, Green
MULTISELECT	Multi-select from predefined values	Tags: Sale, New, Featured
PLAIN_TEXT	Unformatted text	Material: "100% Cotton"
RICH_TEXT	Formatted content blocks	Product description
NUMERIC	Numbers with optional units	Weight: 500g
BOOLEAN	Yes/no values	Fair trade certified
DATE / DATE_TIME	Date values	Release date
FILE	File attachments	Product manual PDF
SWATCH	Color codes or images	Visual color picker
REFERENCE	Links to other entities	Related products

Linking Entities with REFERENCE Attributes

Connect products to other products, models, or variants:

productTypes:
  - name: "Perfume"
    productAttributes:
      - name: "Scent Profiles"
        inputType: REFERENCE
        entityType: PAGE          # Links to Models
      - name: "Related Products"
        inputType: REFERENCE
        entityType: PRODUCT       # Links to other Products

Custom Entities with Models

Extend your domain beyond products using Models (internally called Pages):

# Define structure with pageTypes
pageTypes:
  - name: "Brand"
    attributes:
      - name: "Country"
        inputType: DROPDOWN
        values: [{ name: "France" }, { name: "Italy" }, { name: "USA" }]
      - name: "Founded"
        inputType: NUMERIC

# Create instances with models
models:
  - title: "Maison Lumière"
    slug: "maison-lumiere"
    modelType: "Brand"
    attributes:
      country: "France"
      founded: 1925

Structures (Navigation)

Organize entities hierarchically using menus:

menus:
  - name: "Main Navigation"
    slug: "main-nav"
    items:
      - name: "Shop"
        category: "all-products"      # Link to Category
      - name: "Collections"
        children:
          - name: "Summer Sale"
            collection: "summer-sale" # Link to Collection
      - name: "Our Brands"
        page: "maison-lumiere"        # Link to Model
      - name: "Help"
        url: "https://help.example.com"  # External URL

Learn more: Saleor Modeling · Attributes · Products

Entity Identification

Entities are identified by either slug or name depending on their type:

Identifier	Entity Types
slug	Channels, Categories, Collections, Menus, Pages, Products, Warehouses
name	ProductTypes, PageTypes, TaxClasses, ShippingZones, Attributes

When referencing entities, use the appropriate identifier:

products:
  - name: "Sample Book"
    productType: "Book"        # Reference by name (ProductType)
    category: "fiction"        # Reference by slug (Category)
    collections: ["featured"]  # Reference by slug (Collection)

Complete Reference

• SCHEMA.md — Full field documentation and validation rules
• example.yml — Comprehensive working example

Recipes

Recipes are pre-built YAML configuration templates for common e-commerce scenarios. They complement the Saleor Recipes documentation by providing ready-to-deploy configurations you can apply directly or customize.

Available Recipes

Recipe	Description	Entities
multi-region	US, EU, UK markets with regional warehouses	Channels, Warehouses, ShippingZones
digital-products	Product types for non-physical goods	ProductTypes
click-and-collect	Warehouse pickup points with local collection	Warehouses, ShippingZones
custom-shipping	Complex shipping zones and rate structures	ShippingZones

Quick Start with Recipes

# List all recipes with descriptions
npx @saleor/configurator recipe list

# Preview what a recipe contains
npx @saleor/configurator recipe show multi-region

# Apply directly to your instance
npx @saleor/configurator recipe apply multi-region --url <URL> --token <TOKEN>

# Export and customize before applying
npx @saleor/configurator recipe export multi-region --output my-store.yml
# Edit my-store.yml...
npx @saleor/configurator deploy --url <URL> --token <TOKEN> --config my-store.yml

Note: More recipes are planned. Check recipe list for the current catalog.

See recipes/README.md for detailed recipe documentation and customization guides.

CI/CD Integration

Automate configuration deployments with GitHub Actions or other CI systems.

GitHub Actions Example

name: Deploy Saleor Configuration

on:
  push:
    branches: [main]
    paths: ['config.yml']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Preview changes
        run: |
          npx @saleor/configurator diff \
            --url ${{ secrets.SALEOR_URL }} \
            --token ${{ secrets.SALEOR_TOKEN }}

      - name: Deploy configuration
        run: |
          npx @saleor/configurator deploy \
            --url ${{ secrets.SALEOR_URL }} \
            --token ${{ secrets.SALEOR_TOKEN }} \
            --ci

Key Flags for Automation

Flag	Description
--ci	Skip all confirmation prompts
--json	Output machine-readable JSON
--quiet	Suppress non-essential output

Multi-Environment Pattern

# Production deployment
npx @saleor/configurator deploy \
  --url $PROD_URL --token $PROD_TOKEN \
  --config config.yml --ci

# Staging deployment
npx @saleor/configurator deploy \
  --url $STAGING_URL --token $STAGING_TOKEN \
  --config config.yml --ci

See docs/ci-cd/README.md for workflow templates, exit codes, and advanced patterns.

Troubleshooting

Common Issues

Authentication Failed

• Verify your token in the Saleor dashboard
• Ensure the app has all required permissions
• Check that the URL ends with /graphql/

Entity Reference Errors

• Verify referenced entities exist (e.g., categories before products)
• Check identifier types: use slug for categories, name for product types
• Run diff to see what's missing

Validation Errors

• Check required fields are present
• Validate enum values match the schema
• See SCHEMA.md for field requirements

Diagnostic Commands

# Test connectivity
npx @saleor/configurator introspect --url <URL> --token <TOKEN> --include shop

# Preview without changes (show plan only)
npx @saleor/configurator deploy --url <URL> --token <TOKEN> --plan

# Debug mode
LOG_LEVEL=debug npx @saleor/configurator diff --url <URL> --token <TOKEN>

See docs/TROUBLESHOOTING.md for detailed troubleshooting procedures.

Contributing

Development Setup

# Clone and install
git clone https://github.com/saleor/configurator.git
cd configurator
pnpm install

# Run in development mode
pnpm dev start
pnpm dev introspect --url <URL> --token <TOKEN>

# Build and test
pnpm build
pnpm test

Quality Standards

# Before committing
pnpm check:fix && pnpm build && pnpm test

Versioning

This project uses Changesets for version management:

# Document your changes
pnpm changeset

See docs/DEVELOPMENT_WORKFLOWS.md for detailed contribution guidelines.

Documentation

Document	Description
SCHEMA.md	Complete configuration field reference
example.yml	Working example with all entity types
recipes/README.md	Pre-built recipe templates
docs/COMMANDS.md	Complete CLI reference
docs/ci-cd/README.md	CI/CD integration guide
docs/ENTITY_REFERENCE.md	Entity types and identification
docs/TROUBLESHOOTING.md	Problem diagnosis and fixes
docs/ARCHITECTURE.md	System design and internals
docs/DEVELOPMENT_WORKFLOWS.md	Contributor guide
docs/CODE_QUALITY.md	Coding standards
docs/TESTING_PROTOCOLS.md	Testing guidelines

License

MIT License - see LICENSE for details.