configurator

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

Saleor Configurator

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

npm version License: MIT

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

# 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> --fail-on-delete

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>

# 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 }} \

Key Flags for Automation

Flag Description
--json Output machine-readable JSON
--fail-on-delete Exit code 6 if deletions detected
--fail-on-breaking Exit code 7 if breaking changes detected
--quiet Suppress non-essential output

Non-interactive mode is auto-detected in non-TTY environments (pipes, CI, subprocesses).

Multi-Environment Pattern

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

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

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.

AI Agent Integration

Saleor Configurator provides first-class support for AI coding tools through two mechanisms:

Portable Skills (skills/)

Nine portable skills usable by any AI coding tool (Codex, Cursor, Copilot, Gemini CLI, etc.):

# Install via skills.sh
npx skills add saleor/configurator

Skills cover CLI usage, config schema, Saleor domain modeling, product design, recipes, data import, output parsing, deployment workflows, and troubleshooting.

Claude Code Plugin (plugin/)

Full-featured Claude Code plugin with slash commands, autonomous agents, hooks, and MCP integrations:

claude --plugin-dir ./plugin

See AGENTS.md for the complete AI agent integration guide.

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 release notes and publishing, with one repository-specific rule: configurator package major and minor versions follow the supported Saleor major and minor.

# Document your changes
pnpm changeset

Release rules:

  • Patch fixes for the current Saleor target use a patch changeset.
  • Moving support to the next Saleor minor updates package.json#saleor.schemaVersion and uses a minor changeset.
  • The first Saleor-bound release from 1.x to 3.23.0 requires manually editing the generated release PR version.
  • Releases are published from main by the GitHub Actions release workflow.

For example, configurator 3.23.x targets Saleor 3.23.x; configurator 3.24.0 starts the Saleor 3.24.x line.

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.

本页内容由上游仓库自动镜像，如有疑问请访问原始仓库。