saleor-development

What this skill does

# Saleor Development

## Overview

Saleor is a headless, GraphQL-first e-commerce platform built on Django and Python. It exposes a fully typed GraphQL API for storefronts and third-party apps, a React-based dashboard for store management, and an extension system that lets you react to events via webhooks or inject UI into the dashboard. This skill covers querying the Saleor API, building Saleor Apps (plugins hosted outside Saleor), and customizing the dashboard with App Extensions.

## When to Use This Skill

- When building a custom storefront (Next.js, Remix, mobile) against a Saleor backend
- When creating a Saleor App that reacts to order or product lifecycle webhooks
- When injecting custom UI panels into the Saleor Dashboard via App Extensions
- When exploring or extending the Saleor product catalog, checkout, or customer APIs
- When setting up a local Saleor development environment with Docker

## Prerequisites & Platform Notes

**This skill is written for custom/headless storefronts** (Node.js, Python, or similar backend). The code examples use TypeScript/Node.js and can be adapted to any stack.

**Shopify**: Shopify Hydrogen is Shopify's headless framework. MACH/composable patterns apply when using Shopify as the commerce backend with a custom frontend, or when mixing Shopify with other best-of-breed services.
**WooCommerce**: WooCommerce can serve as a headless backend via its REST API and WPGraphQL. These patterns apply when decoupling the frontend from WordPress.
**Magento**: Magento's GraphQL API and PWA Studio support headless architectures. These composable patterns apply to Magento as a backend service in a MACH stack.

**You'll need**:
- Node.js 18+ (or adapt to your backend language)
- PostgreSQL (or your preferred relational database)
- Redis for caching/queues
- Stripe account and API keys
- An email sending service (SendGrid, AWS SES, or Postmark)
- Docker and/or Kubernetes for container orchestration
- CDN (Cloudflare, CloudFront, or Fastly)

## Core Instructions

1. **Run Saleor locally with Docker Compose**

   ```bash
   git clone https://github.com/saleor/saleor-platform.git
   cd saleor-platform
   docker compose up --detach
   # API:       http://localhost:8000/graphql/
   # Dashboard: http://localhost:9000
   ```

   Create the first superuser and populate demo data:
   ```bash
   docker compose run --rm api python manage.py createsuperuser
   docker compose run --rm api python manage.py populatedb --createsuperuser
   ```

2. **Query the Storefront GraphQL API**

   Use the Saleor CLI or any GraphQL client (Apollo, urql, graphql-request).

   Install the CLI for code generation:
   ```bash
   npm install -g @saleor/cli
   saleor configure
   ```

   Example — fetch the first 12 products from the default channel:
   ```graphql
   query ProductList($channel: String!) {
     products(first: 12, channel: $channel) {
       edges {
         node {
           id
           name
           slug
           thumbnail { url alt }
           pricing {
             priceRange {
               start { gross { amount currency } }
             }
           }
         }
       }
       pageInfo { hasNextPage endCursor }
     }
   }
   ```

   ```javascript
   import { createClient } from 'urql';

   const client = createClient({
     url: process.env.NEXT_PUBLIC_SALEOR_API_URL,
     fetchOptions: () => ({
       headers: { 'Content-Type': 'application/json' },
     }),
   });

   const { data } = await client.query(PRODUCT_LIST_QUERY, { channel: 'default-channel' }).toPromise();
   ```

3. **Authenticate a customer and start checkout**

   ```graphql
   mutation CustomerLogin($email: String!, $password: String!) {
     tokenCreate(email: $email, password: $password) {
       token
       refreshToken
       errors { field message }
       user { id email }
     }
   }
   ```

   Create a checkout and add lines:
   ```graphql
   mutation CheckoutCreate($channel: String!, $lines: [CheckoutLineInput!]!) {
     checkoutCreate(input: { channel: $channel, lines: $lines }) {
       checkout {
         id
         token
         totalPrice { gross { amount currency } }
       }
       errors { field message }
     }
   }
   ```

   Complete checkout with a payment gateway token (e.g., from Stripe Elements):
   ```graphql
   mutation CheckoutComplete($checkoutId: ID!, $paymentData: JSONString) {
     checkoutComplete(id: $checkoutId, paymentData: $paymentData) {
       order { id number status }
       errors { field message code }
     }
   }
   ```

4. **Bootstrap a Saleor App**

   A Saleor App is a Node.js service that registers itself with Saleor, receives webhooks, and optionally renders UI in the dashboard via iframes.

   ```bash
   npx @saleor/app-sdk@latest create my-saleor-app
   cd my-saleor-app
   npm install
   npm run dev
   # Expose with: npx ngrok http 3000
   ```

   Register the app in the dashboard under **Apps → Install custom app**, entering your ngrok URL. Saleor calls your `/api/manifest` endpoint:

   ```typescript
   // pages/api/manifest.ts
   import { createManifestHandler } from "@saleor/app-sdk/handlers/next";
   import { AppManifest } from "@saleor/app-sdk/types";

   const manifest: AppManifest = {
     id: "my-saleor-app",
     name: "My Saleor App",
     version: "1.0.0",
     about: "Example app",
     permissions: ["MANAGE_ORDERS"],
     appUrl: process.env.APP_URL!,
     tokenTargetUrl: `${process.env.APP_URL}/api/register`,
     webhooks: [
       {
         name: "Order Created",
         asyncEvents: ["ORDER_CREATED"],
         query: `subscription { event { ... on OrderCreated { order { id number } } } }`,
         targetUrl: `${process.env.APP_URL}/api/webhooks/order-created`,
         isActive: true,
       },
     ],
   };

   export default createManifestHandler({ manifestFactory: () => manifest });
   ```

5. **Handle Saleor webhooks securely**

   Saleor signs every webhook with an HMAC-SHA256 signature using your app's secret token.

   ```typescript
   // pages/api/webhooks/order-created.ts
   import { SaleorAsyncWebhook } from "@saleor/app-sdk/handlers/next";
   import { OrderCreatedDocument } from "@/generated/graphql";

   const orderCreatedWebhook = new SaleorAsyncWebhook<OrderCreatedPayload>({
     name: "Order Created",
     webhookPath: "api/webhooks/order-created",
     asyncEvent: "ORDER_CREATED",
     apl: saleorApp.apl,
     query: OrderCreatedDocument,
   });

   export default orderCreatedWebhook.createHandler((req, res, ctx) => {
     const { order } = ctx.payload;
     console.log(`New order #${order.number} received`);
     // Trigger fulfillment, email, ERP sync, etc.
     return res.status(200).end();
   });

   export const config = { api: { bodyParser: false } }; // required for signature check
   ```

6. **Add a Dashboard Extension (custom UI panel)**

   Extensions render an iframe inside the Saleor Dashboard. Declare them in the manifest:

   ```typescript
   extensions: [
     {
       label: "Sync to ERP",
       mount: "PRODUCT_DETAILS_MORE_ACTIONS",
       target: "POPUP",
       permissions: ["MANAGE_PRODUCTS"],
       url: `${process.env.APP_URL}/extension/product-sync`,
     },
   ],
   ```

   The extension page uses `@saleor/app-sdk` to communicate with the dashboard host:

   ```typescript
   import { actions, useAppBridge } from "@saleor/app-sdk/app-bridge";

   export default function ProductSyncExtension() {
     const { appBridge } = useAppBridge();

     const handleSync = async () => {
       appBridge?.dispatch(actions.Notification({
         status: "success",
         title: "Sync started",
         text: "Product is being synced to ERP.",
       }));
     };

     return <button onClick={handleSync}>Sync to ERP</button>;
   }
   ```

## Examples

### Paginated product catalog with TypeScript and graphql-request

```typescript
import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient(process.env.SALEOR_API_URL!, {
  header