Warning
This project is in early development. Please use with caution.
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 startQuickstart:
- Create an app token with all permissions in your Saleor dashboard.
Tip
You can also use the start command to explore the features interactively.
- Introspect your current configuration from your remote Saleor instance to
config.yml:
pnpm dlx @saleor/configurator introspect --url https://your-store.saleor.cloud/graphql/ --token your-app-token- Modify the pulled configuration according to your needs.
Note
Here are a bunch of tips for working with the configuration file:
👉🏻 Writing Configuration: You can find the example configuration in example.yml and SCHEMA.md for detailed documentation of all available fields.
👉🏻 Incremental Changes: Introduce your changes incrementally. Add a small change, run pnpm dlx @saleor/configurator diff to see what would be applied, and then push it.
👉🏻 Backup Your Data: Before applying changes, make sure to back up your database or snapshot your instance in Saleor Cloud.
👉🏻 Configuration as Source of Truth: Configurator treats your local configuration file as the authoritative source for your Saleor instance. This means any entities (channels, product types, attributes, etc.) that exist in your Saleor instance but are not defined in your configuration will be flagged for removal during the deploy operation.
- Review changes with the diff command to see what changes would be applied to your Saleor instance:
pnpm dlx @saleor/configurator diff --url https://your-store.saleor.cloud/graphql/ --token your-app-token- If you're happy with the changes, push them to your Saleor instance:
pnpm dlx @saleor/configurator deploy --url https://your-store.saleor.cloud/graphql/ --token your-app-tokenTip
Use --help with any command to see all available options and examples.
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 startDeploys 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 --helpArguments:
--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 --helpArguments:
--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 --helpArguments:
--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.
shop:
customerAllowedToSetExternalReference: false
defaultMailSenderName: "Saleor Store"
defaultMailSenderAddress: "[email protected]"
displayGrossPrices: true
channels:
- name: Poland
currencyCode: PLN
defaultCountry: PL
slug: poland
isActive: false
productTypes:
- name: Book
isShippingRequired: false
productAttributes:
- name: Author
inputType: PLAIN_TEXT
- name: Genre
inputType: DROPDOWN
values:
- name: Fiction
- name: Non-Fiction
variantAttributes:
- name: Size
inputType: DROPDOWN
values:
- name: Small
- name: Medium
- name: Large
products:
- name: "Sample Fiction Book"
productType: "Book"
category: "Fiction"
attributes:
Author: "Jane Doe"
Genre: "Fiction"
variants:
- name: "Hardcover"
sku: "BOOK-001-HC"
weight: 1.2
attributes:
Size: "Large"
channelListings: []Tips:
- See example.yml for an example configuration and SCHEMA.md for detailed documentation of all available fields.
- If you need to reuse an attribute across multiple product or page types, you can define it once and reference with the
attribute: <attribute-name>property. Here is an example:
pageTypes:
- name: Blog Post
attributes:
- name: Published Date # Define a new attribute
inputType: DATE
- name: Article
attributes:
- attribute: Published Date # Reference the existing attributeThe following features are not yet supported in the current version:
- Attribute Values: Cannot add attribute values directly to products or variants
- Variant Channel Listings: Cannot add channel listings to individual variants
These limitations will be addressed in future releases.
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.tsThis 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 changesetSkip changesets: Add the skip-changeset label to PRs that don't need versioning (docs, tests, internal changes).