Saleor Configurator is a "commerce as code" tool that helps you automate the creation and management of data models in Saleor. Instead of manually creating product types, attributes, products, and variants, you can define them in a configuration file and let the tool handle the synchronization with your Saleor instance.

Prerequisites:

• Node.js 20+

Usage:

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

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

Quickstart:

1. Create an app token with all permissions in your Saleor dashboard.

2. Introspect your current configuration from your remote Saleor instance:

pnpm dlx @saleor/configurator introspect --url https://your-store.saleor.cloud/graphql/ --token your-app-token

3. Modify the configuration to define your commerce setup. You can configure:
   • Store settings (shop configuration, channels, tax classes)
   • Product catalog (product types, categories, collections, products)
   • Fulfillment (warehouses, shipping zones and methods)
   • Content management (page types, models, menus)

4. Preview changes before applying:

pnpm dlx @saleor/configurator diff --url https://your-store.saleor.cloud/graphql/ --token your-app-token

5. Deploy your configuration:

pnpm dlx @saleor/configurator deploy --url https://your-store.saleor.cloud/graphql/ --token your-app-token

All commands support the --help flag to display detailed usage information with examples.

Starts the interactive setup wizard that will guide you through the available operations.

pnpm dlx @saleor/configurator start

Deploys the local configuration to the remote Saleor instance with mandatory diff preview and safety confirmations.

# Basic usage with diff preview and confirmation
pnpm dlx @saleor/configurator deploy --url https://your-store.saleor.cloud/graphql/ --token your-app-token

# With custom config file
pnpm dlx @saleor/configurator deploy --url https://your-store.saleor.cloud/graphql/ --token your-app-token --config production.yml

# CI mode (skip all confirmations for automated environments)
pnpm dlx @saleor/configurator deploy --url https://your-store.saleor.cloud/graphql/ --token your-app-token --ci

# Show help
pnpm dlx @saleor/configurator deploy --help

Arguments:

• --url (required): Saleor instance URL
• --token (required): Saleor API token
• --config (optional): Configuration file path (default: config.yml)
• --ci (optional): CI mode - skip all confirmations for automated environments
• --quiet (optional): Suppress output
• --help: Show command help with examples

Shows the differences between the local and remote Saleor instances.

# Basic usage
pnpm dlx @saleor/configurator diff --url https://your-store.saleor.cloud/graphql/ --token your-app-token

# With custom config file
pnpm dlx @saleor/configurator diff --url https://your-store.saleor.cloud/graphql/ --token your-app-token --config production.yml

# Show help
pnpm dlx @saleor/configurator diff --help

Arguments:

• --url (required): Saleor instance URL
• --token (required): Saleor API token
• --config (optional): Configuration file path (default: config.yml)
• --quiet (optional): Suppress output
• --help: Show command help with examples

Shows the current state of the remote Saleor instance and upon confirmation saves it to a configuration file.

# Basic usage (shows diff and asks for confirmation)
pnpm dlx @saleor/configurator introspect --url https://your-store.saleor.cloud/graphql/ --token your-app-token

# With custom config file
pnpm dlx @saleor/configurator introspect --url https://your-store.saleor.cloud/graphql/ --token your-app-token --config production.yml

# Show help
pnpm dlx @saleor/configurator introspect --help

Arguments:

• --url (required): Saleor instance URL
• --token (required): Saleor API token
• --config (optional): Configuration file path (default: config.yml)
• --quiet (optional): Suppress output
• --help: Show command help with examples

Define your Saleor configuration in a YAML file (default: config.yml). For detailed documentation of all available fields, see SCHEMA.md.

# Complete store configuration example
shop:
  defaultMailSenderName: "My Store"
  defaultMailSenderAddress: "store@example.com"
  displayGrossPrices: true
  trackInventoryByDefault: true

channels:
  - name: "United States"
    slug: "us"
    currencyCode: "USD"
    defaultCountry: "US"
    isActive: true

# Tax management
taxClasses:
  - name: "Standard Rate"
    countries:
      - countryCode: "US"
        taxRate: 8.5

# Warehouse and shipping
warehouses:
  - name: "Main Warehouse"
    slug: "main-warehouse"
    email: "warehouse@example.com"
    isPrivate: false
    clickAndCollectOption: "LOCAL"
    address:
      streetAddress1: "123 Commerce Street"
      city: "New York"
      postalCode: "10001"
      country: "US"

shippingZones:
  - name: "US Zone"
    slug: "us-zone"
    countries: ["US"]
    warehouses: ["main-warehouse"]
    channels: ["us"]
    shippingMethods:
      - name: "Standard Shipping"
        type: "PRICE"
        channelListings:
          - channel: "us"
            price: 9.99

# Product catalog structure  
productTypes:
  - name: "Book"
    isShippingRequired: true
    productAttributes:
      - name: "Author"
        inputType: "PLAIN_TEXT"
      - name: "Genre"
        inputType: "DROPDOWN"
        values:
          - name: "Fiction"
          - name: "Non-Fiction"

categories:
  - name: "Books"
    slug: "books"

collections:
  - name: "Featured Books"
    slug: "featured-books"
    channelListings:
      - channel: "us"
        isPublished: true

# Content management
pageTypes:
  - name: "Blog Post"
    attributes:
      - name: "Published Date"
        inputType: "DATE"

models:
  - name: "Welcome Post"
    slug: "welcome"
    modelType: "Blog Post"
    attributes:
      Published Date: "2024-01-01"

menus:
  - name: "Main Menu"
    slug: "main"
    items:
      - name: "Books"
        category: "books"

# Products
products:
  - name: "Sample Book"
    slug: "sample-book"
    productType: "Book"
    category: "books"
    attributes:
      Author: "Jane Doe"
      Genre: "Fiction"
    variants:
      - name: "Hardcover"
        sku: "BOOK-001"
        weight: 1.2

The configurator supports comprehensive store management through these entity types:

• shop - Global store settings (email, pricing, inventory defaults)
• channels - Sales channels with currency, country, and channel-specific settings
• taxClasses - Tax rate definitions by country for products and shipping

• warehouses - Physical storage locations with addresses and settings
• shippingZones - Geographical regions with associated warehouses and shipping methods

• productTypes - Templates defining product structure and attributes
• categories - Hierarchical product organization with subcategories
• collections - Curated product groupings for merchandising
• products - Individual products with variants, pricing, and attributes

• pageTypes - Templates for structured content pages
• models - Content instances based on page types (like blog posts, landing pages)
• menus - Navigation structures linking to categories, collections, or external URLs

Attribute Reuse - Define attributes once, reference across entity types:

pageTypes:
  - name: "Blog Post"
    attributes:
      - name: "Published Date"  # Define once
        inputType: "DATE"
  - name: "Article" 
    attributes:
      - attribute: "Published Date"  # Reuse existing

Entity References - Link entities using their identifiers (slugs for most, names for types):

products:
  - name: "Sample Book"
    productType: "Book"        # Reference by name
    category: "fiction"        # Reference by slug
    collections: ["featured"]  # Reference by slug

Resources:

• example.yml - Complete working configuration
• SCHEMA.md - Detailed field documentation

For contributors and advanced users who want to modify the tool.

The configuration schema is automatically documented from Zod schemas with GraphQL field mappings. The SCHEMA.md file is automatically regenerated on push.

Manual generation (if needed):

pnpm run generate-schema-docs

# Install dependencies
pnpm install

# Run CLI in development mode with TypeScript
pnpm dev start

# Build the bundled CLI
pnpm build

# Test the bundled CLI locally
node dist/main.js --help
node dist/main.js start

# Run specific commands in development
pnpm dev introspect --url https://your-store.saleor.cloud/graphql/ --token your-token
pnpm dev deploy --url https://your-store.saleor.cloud/graphql/ --token your-token

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Run specific test file
pnpm test src/modules/product/product-service.test.ts

This project uses Changesets for version management and changelog generation.

Please execute the following command when making changes that should be released:

# Document your changes
pnpm changeset

Skip changesets: Add the skip-changeset label to PRs that don't need versioning (docs, tests, internal changes).