This article focuses on developing apps connected to Saleor hosted in the cloud. You can also develop them locally, using Saleor Platform, without access to internet. Read more about developing apps locally
What is a tunnel, and why do you need one?
The Saleor extendability model relies on the concept of Apps. If you want to read more about them, head to the Apps Overview page.
As you want Apps to react to events in your store, you reach for webhooks. However, webhooks pose a unique challenge: they can only communicate with public clients. If so, how are you supposed to develop your app on
This is where tunnels come into play. A tunnel allows you to create a proxy that exposes a local environment to a public URL.
Let's say you are building a Next.js application that leverages a webhook. You boot it up with the
next dev command, which renders it on
http://localhost:3000. Since this address is only reachable from your machine and is not HTTPS compliant, the webhook cannot reach the app. We have a perfect use case for a tunnel on our hands.
A simplified process of using a tunnel to expose this app would look like this:
- Start the dev server of your application.
- You authenticate yourself in the tunneling service of your choosing (e.g.:
- You provide the tunnel with the port number
3000(where your app is running).
- The tunnel will provide a publicly available URL of your application.
- Now you can install your application in Saleor Cloud and receive webhooks 🎉.
Saleor App Tunnel
Saleor CLI provides a built-in tunneling solution. It is a wrapper around ngrok, a popular tunneling service, and it provides additional features on top of it like automatic installation of the Saleor App. It is the recommended way of tunneling your apps, as it simplifies the process and provides a better developer experience.
To use Saleor App Tunnel, you must install Saleor CLI:
npm i -g @saleor/cli
saleor app tunnel --help to check detailed usage, like changing the used port or forced installation of the App.
To create a tunnel, run
saleor app tunnel inside the App directory. After several seconds, the CLI should print a URL with the
$ saleor app tunnel
✔ Organization · YourShop
✔ Select Environment · staging
✔ Environment · staging
Saleor App Name: Your app
Saleor App URL: https://your-app-shop.ngrok.app
Saleor Dashboard: https://yourshop.eu.saleor.cloud/dashboard/
GraphQL Playground: https://yourshop.eu.saleor.cloud/graphql/
Tunnel is listening to your local machine on port: 3000
Press CTRL-C to stop the tunnel
If you experience any issues with the Saleor App Tunnel, please file an issue here.
While we encourage you to use Saleor App Tunnel, Saleor will work with any tunneling solution. They will all follow a set-up process similar to the Saleor App Tunnel.
The list of verified Saleor App Tunnel alternatives features:
Installing the App in the Dashboard
By default, Saleor CLI with the
saleor app tunnel command will install the Saleor App in the Dashboard. While developing Saleor Apps there will be times when you would need to install the App once again like after adding additional permissions or when your tunnel URL expires. In that case, use the
--force-install flag which will reinstall the App in the Dashboard.
saleor app tunnel --force-install # sets up the tunnel and re-installs the App
By convention Saleor CLI expects the manifest exposed by the App to be available at
/api/manifest. You can change it by providing your custom manifest path to
saleor app tunnel --manifest-path=/manifest # sets up the manifest path and installs the App
If your Saleor App is already exposed on the internet, Saleor CLI allows the installation of the App in the Dashboard without setting up the tunnel. To do that use the
saleor app install command.
saleor app install --manifest-URL=https://my-saleor-app.com/api/manifest # installs the App in the Dashboard