saleor-configurator

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+

Compatibility

Configurator releases follow the supported Saleor major and minor version. Configurator 3.23.x targets Saleor 3.23.x.

The supported Saleor minor is declared in package.json#saleor.schemaVersion. Patch versions within that Saleor minor are treated as compatible. Older Saleor minors may still work, but they are not active support targets for the latest configurator line.

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