> Documentation index: [Saleor](/llms.txt) · [This section](/developer/llms.txt)
> Source: https://docs.saleor.io/developer/extending/apps/local-app-development

# 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](/developer/extending/apps/developing-with-tunnels.md).

If you are a Linux user, you can [skip to this section](#working-on-linux).

<a id="prerequisites"></a>

## Prerequisites

This article will require you to have installed the following:

-   [Docker](https://www.docker.com/) - for running Saleor locally
-   [Node.js](https://nodejs.org/en/) (v22) - to run a Node.js app locally
-   [pnpm](https://pnpm.io/) (v10 or higher) - to install dependencies of the [Saleor App Template](/developer/extending/apps/developing-apps/app-template.md)

<a id="setting-up-the-local-development-environment"></a>

## Setting up the local development environment

The easiest way to set up up-to-date Saleor ecosystem is to use official [Saleor Platform](https://github.com/saleor/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](https://github.com/saleor/saleor-platform) in the Saleor Platform repository.

You also need to change one environment variable value. Please open `common.env` file and set:

```text
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:

-   Saleor Core (API) - [http://localhost:8000](http://localhost:8000)
-   Saleor Dashboard - [http://localhost:9000](http://localhost:9000)

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

<a id="setting-up-saleor-app-template"></a>

## 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](https://github.com/saleor/saleor-app-template) - the official Saleor app boilerplate.

To set up Saleor App Template, follow the instructions in [this article](/developer/extending/apps/developing-apps/app-template.md).

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](https://nextjs.org/) 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

<a id="connecting-the-app-to-saleor-in-docker"></a>

## Connecting the app to Saleor (in Docker)

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).

<a id="apps-url-overriding"></a>

### 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](https://docs.docker.com/desktop/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host) in the Docker documentation.

Saleor App Template ships with a documented [`.env.example` file](https://github.com/saleor/saleor-app-template/blob/main/.env.example) 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:

```sh
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](https://github.com/saleor/saleor-app-template/blob/main/src/pages/api/manifest.ts) 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](http://localhost:3000). You can open it in the browser and see if everything works.

<a id="connecting-the-app-to-saleor-running-locally"></a>

## Connecting the app to Saleor (running locally)

If you've decided to run Saleor locally, without docker, you can skip setting up env variables from previous section.

Depending on your `hosts` file, you might have different IP resolution for `localhost`. If your setup uses IPv6 addresses your app might fail installation. In that case, you can set the `PUBLIC_URL` to `http://127.0.0.1:8000/` (or whatever port your Saleor is running on).

note

If you have following errors you'll need to setup `PUBLIC_URL` env variable:

App logs: `Error: No client has been specified using urql's Provider. please create a client and add a Provider.` Saleor logs: `The auth data given during registration request could not be used to fetch app ID.`

If you are still having issues with your setup, try setting `DEBUG=app-sdk:*` env variable to see all logs from Saleor App SDK.

<a id="installing-app-in-saleor"></a>

### 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](http://localhost:9000))
2.  Navigate to the _Apps_ section ([http://localhost:9000/apps](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.

<a id="working-on-linux"></a>

## 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`.