This article will require you to have installed the following:
- Docker - for running Saleor locally
- Node.js (v18 or higher) - to run a Node.js app locally
- pnpm (v8 or higher) - to install dependencies of the Saleor App Template
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:
When you finish, you should be able to run the
docker-compose command and see Saleor running locally together with the Dashboard.
Default addresses in the Saleor Platform are:
- Saleor Core (API) - http://localhost:8000
- Saleor Dashboard - http://localhost:9000
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.
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
Once you visit the app in your browser, you should see a simple welcome page.
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:
- Dashboard needs to open the App (host browser).
- App needs to call Saleor API (host -> container).
- 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
- For Saleor in the container, the app will be available on
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:
: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:
appUrlwhich Dashboard uses to open the app in the iframe, should be using "localhost".
- Other API endpoints should be using
host.docker.internalto ensure container can reach them.
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:
- Open Dashboard (http://localhost:9000)
- Navigate to the Apps section (http://localhost:9000/apps)
- Click on "Install external app" button and paste your
- Continue with the installation process.
Your app should be soon available on the Apps' list. You can open it and see if it works.
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