orcaqubits/saleor-apps

Saleor App Development

Before writing code

Fetch live docs:

1. Fetch https://docs.saleor.io/docs/developer/extending/apps/overview for Apps architecture
2. Web-search site:docs.saleor.io saleor app manifest structure for manifest reference
3. Web-search site:docs.saleor.io saleor-app-sdk token exchange APL for SDK utilities
4. Web-search site:github.com saleor/saleor-app-template for latest Next.js App template
5. Web-search site:docs.saleor.io app permissions for permission enumeration
6. Web-search site:docs.saleor.io app bridge dashboard extensions for Bridge API

App Architecture

Saleor Apps are standalone web applications that extend Saleor functionality. They are not monolithic plugins embedded in the core -- each App is an independent service that communicates with Saleor via GraphQL and webhooks.

| Aspect | Detail | |--------|--------| | Deployment | Standalone web app (any host) | | Communication | GraphQL API + webhooks | | Framework | Any (official template uses Next.js) | | Registration | Installed via manifest URL | | Authentication | App token issued during installation | | Dashboard UI | Rendered in an iframe via App Bridge |

Legacy Plugins Deprecation

Saleor's legacy plugin system (Python classes in saleor/plugins/) is deprecated. All new extensions should be built as Apps. Legacy plugins will be removed in a future major version.

App Manifest

The manifest is a JSON document served at a public URL that describes the App:

| Field | Type | Purpose | |-------|------|---------| | id | string | Unique identifier for the App | | version | string | Semantic version | | name | string | Display name | | about | string | Short description | | permissions | string[] | Required Saleor permissions | | appUrl | string | Main App URL (loaded in Dashboard iframe) | | configurationUrl | string | App settings page URL | | tokenTargetUrl | string | URL that receives the auth token during install | | dataPrivacyUrl | string | Privacy policy URL | | homepageUrl | string | App homepage URL | | supportUrl | string | Support contact URL | | webhooks | object[] | Webhook subscriptions | | extensions | object[] | Dashboard mounting points |

The manifest URL is provided when installing the App via the Dashboard or the appInstall mutation.

saleor-app-sdk

The official TypeScript SDK provides core utilities for building Saleor Apps:

| Utility | Purpose | |---------|---------| | SaleorApp | Main App class coordinating APL, manifest, handlers | | createManifestHandler | Next.js API route handler for manifest endpoint | | createAppRegisterHandler | Handler for the token exchange callback | | withRegisteredSaleorDomainHeader | Middleware to verify request origin | | verifyJWT | Verify Saleor-issued JWTs in webhook requests | | getAppId | Retrieve the App's ID from the token | | SALEOR_API_URL_HEADER | Standard header name for Saleor instance URL | | SALEOR_AUTHORIZATION_BEARER_HEADER | Standard header for App auth token |

Install via npm install @saleor/app-sdk -- fetch live docs for the current version.

Auth Persistence Layer (APL)

The APL stores the mapping between Saleor instance URLs and the App's auth tokens:

| APL Type | Storage | Use Case | |----------|---------|----------| | FileAPL | Local JSON file | Development only | | UpstashAPL | Upstash Redis | Serverless production | | SaleorCloudAPL | Saleor Cloud | Apps deployed to Saleor Cloud | | EnvAPL | Environment variable | Single-tenant simple deployments | | Custom | Any store | Implement the APL interface |

The APL is critical -- without it, the App cannot authenticate requests from Saleor after a server restart.

App Installation Flow

| Step | Actor | Action | |------|-------|--------| | 1 | Admin | Provides manifest URL in Dashboard | | 2 | Saleor | Fetches manifest, validates permissions | | 3 | Saleor | Sends auth token to tokenTargetUrl | | 4 | App | Stores token in APL | | 5 | Saleor | Marks App as installed | | 6 | App | Uses stored token for all future API calls |

App Permissions

| Permission | Scope | |------------|-------| | MANAGE_PRODUCTS | Create, update, delete products | | MANAGE_ORDERS | View and manage orders | | MANAGE_CHECKOUTS | Manage checkout sessions | | MANAGE_USERS | View and manage customers | | MANAGE_SHIPPING | Configure shipping methods | | MANAGE_DISCOUNTS | Create and manage promotions | | MANAGE_CHANNELS | Configure channels | | MANAGE_APPS | Install and manage other Apps | | HANDLE_PAYMENTS | Process payment transactions | | HANDLE_TAXES | Calculate taxes for checkout |

Request only the permissions your App actually needs -- the principle of least privilege.

App Template (Next.js)

The official saleor-app-template scaffolds a Next.js App with all SDK wiring:

| File | Purpose | |------|---------| | pages/api/manifest.ts | Serves the App manifest | | pages/api/register.ts | Handles token exchange | | pages/api/webhooks/*.ts | Webhook handler endpoints | | pages/index.tsx | Main App page (Dashboard iframe) | | saleor-app.ts | SaleorApp instance and APL configuration | | lib/saleor-client.ts | Authenticated GraphQL client factory |

Scaffold with npx @saleor/cli app create -- fetch live docs for current template version.

Local Development

| Task | Command / Tool | |------|---------------| | Start dev server | npm run dev (Next.js on port 3000) | | Expose locally | saleor app tunnel or ngrok | | Install in Saleor | Provide tunnel URL as manifest URL | | View logs | Check terminal output and Saleor Dashboard App logs | | Test webhooks | Use tunnel + Saleor triggers |

The tunnel is required because Saleor must reach your App over HTTPS to deliver webhooks and fetch the manifest.

Authenticated GraphQL Client

After installation, use the stored auth token to call the Saleor API:

// lib/saleor-client.ts
// Fetch live docs for current client setup pattern
import { createGraphQLClient } from "@saleor/apps-shared"

export function createClient(saleorApiUrl: string, token: string) {
  return createGraphQLClient({ saleorApiUrl, token })
}

Best Practices

• Build all new extensions as Apps, not legacy plugins
• Store auth tokens securely using an appropriate APL for your deployment target
• Request only the permissions your App needs -- follow least privilege
• Use subscription queries in webhook definitions for precise payload control
• Verify webhook signatures (JWS default since 3.5+, HMAC deprecated) before processing any payload
• Use saleor app tunnel during development for reliable webhook delivery
• Handle the SALEOR_API_URL_HEADER to support multi-tenant App installations
• Test the full install/uninstall lifecycle before deploying to production

Fetch the Saleor Apps documentation for exact manifest fields, SDK method signatures, and APL configuration patterns before implementing.