mcpField
S
saleor-app

saleor-app

github.com/saleorDevelopment2427 installsUpdated 13w ago
Repository

About saleor-app

saleor-app is a development guide for building apps that extend Saleor, aimed at developers working with APIs, webhooks, payments, and Dashboard UI. It groups framework-agnostic rules by priority and includes Next.js examples.

Key features

  1. 01App manifest and registration rules
  2. 02Sync and async webhook handling
  3. 03Payment apps and Transaction API guidance
  4. 04GraphQL authentication and data settings
  5. 05Dashboard iframe UI rules
  6. 06Permission scopes and access control

Use cases

  1. 01Define an app manifest and register webhooks
  2. 02Implement a Saleor payment app
  3. 03Troubleshoot webhook or authentication errors
  4. 04Build app UI inside the Dashboard iframe

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/saleor/agent-skills --skill saleor-app

After installing, type/saleor-appin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.md
references/
apl-implementations.md
app-manifest-schema.md
rules/
dashboard-appbridge.md
data-graphql.md
data-settings.md
dev-debug.md
payment-app.md
permissions-access-scopes.md
protocol-auth.md
protocol-manifest.md
webhook-async.md
webhook-external.md
webhook-sync.md

Details

From the project README

Saleor App

Guide for building apps that extend Saleor via webhooks and the GraphQL API. Framework-agnostic protocol documentation with Next.js examples using @saleor/app-sdk.

When to Apply

  • Defining an app manifest or registering webhooks
  • Handling async/sync webhook events from Saleor
  • Building payment apps with the Transaction API and provider webhooks
  • Authenticating requests (registration handshake, JWT, signature verification)
  • Storing app settings in Saleor metadata
  • Building Dashboard UI inside the iframe
  • Making GraphQL calls with app tokens
  • Debugging webhook failures, auth errors, or permission issues
  • Deciding who can view the app and what they should see (user vs app scope)

Rule Categories by Priority

PriorityCategoryImpactPrefix
1ProtocolCRITICALprotocol-
2PermissionsCRITICALpermissions-
3Payment AppsCRITICALpayment-
4WebhooksHIGHwebhook-
5Data & SettingsHIGHdata-
6Dashboard UIMEDIUMdashboard-
7DevelopmentMEDIUMdev-

Quick Reference

1. Protocol (CRITICAL)
  • protocol-manifest — App manifest, required endpoints, permissions, extensions
  • protocol-auth — Registration handshake, APL, token scopes, JWT/signature verification
2. Permissions (CRITICAL)
  • permissions-access-scopes — Define per-feature permissions; guard user JWT on every API route; baseline + per-route meta; UI mirrors server
3. Payment Apps (CRITICAL)
  • payment-app — Financial truth, stable references, unknown outcomes, refunds, and reconciliation
4. Webhooks (HIGH)
  • webhook-async — Async event handling, payload typing, retry policy, signature verification
  • webhook-sync — Sync event handling, response schemas, performance constraints
  • webhook-external — Receiving webhooks from external services, multi-tenant routing
5. Data & Settings (HIGH)
  • data-graphql — GraphQL from apps: client setup, auth headers, codegen, app vs user tokens
  • data-settings — MetadataManager, EncryptedMetadataManager, domain-scoped persistence
6. Dashboard UI (MEDIUM)
  • dashboard-appbridge — AppBridge iframe protocol, actions, events, theme/locale sync
7. Development (MEDIUM)
  • dev-debug — Common errors, webhook dry runs, tunnel setup, debugging checklist

Comments

Markdown supported