saleor/apps

Overview

This repository serves as a starting point in the exploration of Saleor apps.

Saleor apps are separate applications that use GraphQL to talk to the Saleor server and receive webhooks with event notifications from Saleor.

docs.saleor.io

Apps list

In the apps folder, you will find the following applications:

• AvaTax - calculates dynamic taxes via AvaTax API.
• CMS - exports products from Saleor to CMS.
• Klaviyo - send Saleor events to Klaviyo, where you can notify customers.
• Products feed - generates product feed XML.
• Search - connects Saleor with search engines.
• Segment - connects Saleor with Twilio Segment.
• SMTP - enables email communication with customers.
• Stripe - connects Saleor with Stripe.
• NP Atobarai - connects Saleor with NP Atobarai (Japanese: NP 後払い).

Example apps

• Slack integration app example
• Taxjar integration app example
• Invoices app example
• CRM app example
• Sendgrid integration app example

Development

You can find the documentation for saleor/apps on docs.saleor.io.

PNPM and corepack

Due to an issue with outdated signatures in Corepack, Corepack should be updated to its latest version first:

npm install --global corepack@latest

After that, run this command to install pnpm with the proper version:

corepack enable pnpm

Turborepo

This repository uses Turborepo remote caching. If you are a Saleor employee, you can leverage it by running the following commands in the root of this repository:

pnpm dlx turbo login
pnpm dlx turbo link

Installing new packages

This has following requirements for improved supply chain security:

• Packages must be older than 21 days
• Added packages must use exact version (no ^ or ~)
• Packages versions cannot have a downgraded provenance security
• All installs are using froze lockfile to prevent unintended changes in transitive dependencies, to update packages anyway, you must use: pnpm install --no-frozen-lockfile

ADR

This repository uses architecture decision records to document architectural decisions. You can find them in the adr directory.

To add a new ADR, follow the guide.

Contributing

We love your contributions and do our best to provide you with mentorship and support. However, please keep in mind that the saleor/apps monorepo is used by Saleor to host apps in Saleor infrastructure. While the code remains open source, the decisions in this repository are made to enable Saleor to maintain features needed by its business goals.

This repository is a one-way mirror of a private repository where development happens, so pull requests here are accepted by copying them upstream rather than by pressing the merge button. Read CONTRIBUTING.md before opening one — it explains what that means for your PR.

If you are looking for an issue to tackle, take a look at issues labeled Good first issue and Help wanted.

If nothing grabs your attention, check our roadmap or start a Discord discussion about a feature you'd like to see. Make sure to read our Contribution Guidelines before opening a PR or issue.

Forking

You can fork this repository to modify and self-host one of the apps. Keep in mind that this is a monorepo, which adds two additional steps to the process:

• When forking, all the apps are forked, even if you need only one.
• There are shared dependencies between apps, stored in the packages/ folder. Even if you need only one app, you still need at least some packages.

You can try two techniques to fork the repository:

1. You can fork everything and keep everything. When you back-merge changes, unused apps will be updated without any issues. You need to ensure you run scripts from the context of the app you are interested in, e.g., cd apps/avatax && pnpm dev. Your tooling should be configured to ignore other apps for better performance.
2. You can fork everything and remove the apps you don't need. It will reduce the number of files in your fork, but you may need to modify some scripts to ensure they work properly (e.g., if some root scripts expect multiple apps, they may fail).

Deployment

Apps are written in Next.js and are hosted on Vercel by Saleor. Everyone should be able to host an app on Vercel if the app is configured properly. Apps share common code, but some of the functionalities are app-specific. For example, AvaTax and Segment apps require DynamoDB to run. Check each app's "env" files to verify what must be provided to deploy.

Docker

The repository contains Devcontainers setup which includes Dockerfiles. They are meant for development. At the moment, Saleor doesn't provide official production Dockerfiles. Feel free to write your own, based on the development ones.

APLs

Apps follow the BYOA (bring your own APL) approach. A minimal set of APLs are implemented in the source code, to avoid maintaining unused dependencies and increasing bundle size. You may want to use another APL client, like Redis. In such a case, please ensure your fork does the job. Usually apps contain a single file that imports APL from @saleor/app-sdk. Your fork can ensure this file contains your own APL setup.

MCP

To help AI agents properly interact with Saleor, you can use the Model Context Protocol, which can interact with Saleor by understanding the GraphQL schema.

Start by populating the .env file under the mcp folder with:

MCP_GRAPHQL_ENDPOINT= # Saleor API endpoint (ends with /graphql/)
MCP_GRAPHQL_TOKEN= # local app token (see https://docs.saleor.io/api-usage/authentication#app-authentication for more details)

Make sure that you don't use quotes in env variables (as they will be loaded by the bash script).

Then follow your editor's docs to get started with MCP:

• VS Code
• Cursor
• JetBrains IDE