Skip to main content

Local App Development

note

This article covers the local development workflow. If you want to connect your app to a Saleor Cloud instance, see developing apps with tunnels.

If you are a Linux user, you can skip to this section.

Prerequisites​

This article will require you to have installed the following:

Setting up the local development environment​

The easiest way to set up up-to-date Saleor ecosystem is to use official Saleor Platform repository. It contains all the necessary services and tools to run Saleor locally.

To set up Saleor local development environment, follow the README in the Saleor Platform repository.

From Saleor 3.16, you also need to change one environment variable value. Please open common.env file and set:

HTTP_IP_FILTER_ENABLED=False

When you finish, you should be able to run the docker-compose command and see Saleor running locally together with the Dashboard.

tip

Default addresses in the Saleor Platform are:

Try to open the Dashboard in your browser now. You need to log in successfully before you continue.

Setting up Saleor App Template​

After setting up all the services, we need to create our app. For that purpose, we will leverage Saleor App Template - the official Saleor app boilerplate.

To set up Saleor App Template, follow the instructions in this article.

Make sure you run pnpm install in the app directory to install all the dependencies.

tip

Saleor App Template is built on top of Next.js framework. You can visit Next.js documentation to learn more about it's concepts.

Before we continue, let's ensure our app is properly set up and running.

To do that, run the default pnpm dev script. It should start the app on http://localhost:3000.

Once you visit the app in your browser, you should see a simple welcome page.

note

At this point you should have three required services running:

  • Saleor Core (API) on port 8000
  • Saleor Dashboard on port 9000
  • Saleor App on port 3000

Connecting the app to Saleor​

Now we reached the tricky part. Installing app in Saleor requires bi-directional communication between services:

  1. Dashboard needs to open the App (host browser).
  2. App needs to call Saleor API (host -> container).
  3. Saleor needs to call App API (container -> host).

To achieve that, we need to ensure all services can communicate with each other. While the host machine can access the container's exposed service, the container itself cannot easily access the host.

We will configure the app to work well both with Saleor (container) and the Dashboard (host browser).

App's URL overriding​

By default, your app will run on the http://localhost:3000. This URL is available for the browser, but once Saleor API from the container tries to reach it - it will look for the container's port, not your host's.

We will alter the behavior of the app. Now, depending on "who is asking", it will be available on different hosts.

  • For the browser, the app will be available on http://localhost:3000.
  • For Saleor in the container, the app will be available on http://host.docker.internal:3000.
note

Read more about host.docker.internal in the Docker documentation.

Saleor App Template ships with a documented .env.example file you can rename to .env. The environment variables will be automatically loaded by the app.

To override the app's base URLs, you need to set following envs:

APP_IFRAME_BASE_URL=http://localhost:3000
APP_API_BASE_URL=http://host.docker.internal:3000
note

Remember that :3000 port is the default port Next.js uses for development. If you change it, you need to update the envs accordingly.

You can visit the Manifest endpoint to verify how the envs are used. You should see:

  1. The appUrl which Dashboard uses to open the app in the iframe, should be using "localhost".
  2. Other API endpoints should be using host.docker.internal to ensure container can reach them.
caution

You need to restart your app after changing the envs.

At this point, your app will be still available on http://localhost:3000. You can open it in the browser and see if everything works.

Installing App in Saleor​

The final step is installing the app in Saleor. You can do that via API or the Dashboard. We will use the Dashboard:

  1. Open Dashboard (http://localhost:9000)
  2. Navigate to the Apps section (http://localhost:9000/apps)
  3. Click on "Install external app" button and paste your http://host.docker.internal:3000/api/manifest URL.
  4. Continue with the installation process.

Your app should be soon available on the Apps' list. You can open it and see if it works.

caution

Be careful not to override envs in the deployment environment. By default, the app will use the same endpoint it is reached from. Thanks to that, you can install the App on the cloud like Vercel and use its unique domains for each deployment.

Working on Linux​

This article uses workaround for Docker limitations on non-Linux systems. If you are working on Linux, you can leverage Docker's HOST network to achieve the same result.

To do that, visit your Saleor Platform's docker-compose.yml file and change the network driver to host.