Skip to main content

Tunneling Apps

note

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 localhost?

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:

  1. Start the dev server of your application.
  2. You authenticate yourself in the tunneling service of your choosing (e.g.: ngrok).
  3. You provide the tunnel with the port number 3000 (where your app is running).
  4. The tunnel will provide a publicly available URL of your application.
  5. Now you can install your application in Saleor Cloud and receive webhooks 🎉.

Available tunnels​

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
note

Run 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 ngrok domain:

$ 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/

─────────────────────────────────────────────────────────────────
✔ Installing...

Tunnel is listening to your local machine on port: 3000

Press CTRL-C to stop the tunnel

Expand ▼

Troubleshooting​

If you experience any issues with the Saleor App Tunnel, please file an issue here.

Alternatives​

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 --manifest-path flag.

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