---
title: Test apps locally
description: How to use the 'shopify app dev' command to test your app locally.
source_url:
  html: 'https://shopify.dev/docs/apps/build/cli-for-apps/test-apps-locally'
  md: 'https://shopify.dev/docs/apps/build/cli-for-apps/test-apps-locally.md'
---

# Test apps locally

The [`app dev`](https://shopify.dev/docs/api/shopify-cli/app/app-dev) command lets you test your app changes in real-time on a dev store without deploying. This enables you to iterate quickly while developing extensions, modifying app configuration, and building app functionality.

## Terminal

```terminal
shopify app dev
```

***

## Overview of `app dev`

To preview your app on a dev store, Shopify CLI prompts you to select a dev store to use for testing. If you have only one store, then it's selected automatically.

While running, `app dev` performs the following tasks:

* For apps with local app configuration and/or extensions, it creates a dev preview on your chosen dev store, and a file watcher to sync local changes with that dev preview.
* For apps with [web files](https://shopify.dev/docs/apps/build/cli-for-apps/app-structure#shopify-web-toml), such as those based on the React Router app template, it serves your self-hosted embedded app.
* For apps with extensions that support browser-based preview, such as UI extensions, it starts a local development server for hot module reloading.
* It serves a reverse proxy that routes to these local servers.
* It sets up [external networking](https://shopify.dev/docs/apps/build/cli-for-apps/networking-options) for that proxy server.
* If [enabled in your app config](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration#build), it updates your app URL to reflect the current tunnel or localhost URL.
  * This change is isolated to the chosen dev store and does not affect the app URL on other stores.
* It serves [GraphiQL for the Admin API](https://shopify.dev/docs/api/usage/api-exploration/admin-graphiql-explorer) using your app's credentials and access scopes.

### Clean up the dev preview

When you stop the `app dev` command, the dev preview remains on your store. Your app configuration and extensions will remain active there, until you clean up the dev preview or uninstall the app.

Cleaning a dev preview restores the active released version of your app to your store. If any extensions or configuration are removed in this process, their related data is deleted as well. For example:

* A Discount function you added during `app dev` isn't in the active app version. Any discounts referencing it are deleted.
* A UI extension you placed and configured via the Checkout Editor isn't in the active app version. This placement and configuration are deleted.
* A metaobject definition you added during `app dev` isn't in the active app version. Any metaobjects referencing it are deleted.

To clean a dev preview, you can either:

* Click the **Clean dev preview** button in the [Dev Console](#the-dev-console) in Shopify admin.

* Run the [`app dev clean`](https://shopify.dev/docs/api/shopify-cli/app/app-dev-clean) command:

  ## Terminal

  ```terminal
  shopify app dev clean
  ```

### Reset `app dev` configuration

You can reset the active organization, app instance, and store used by `app dev` via the `--reset` flag:

## Terminal

```terminal
shopify app dev --reset
```

### Use the Dev Console to manage dev previews

The **Dev Console** in Shopify admin provides information about the active dev previews on your store:

* The name of the app being previewed
* The developer who created the preview
* The time of the last extension or configuration update to the preview
* An indication of whether the preview is connected to `app dev` on your local machine
* The extensions that are included in the preview

It also allows you to:

* [Clean up](#cleaning-up-the-dev-preview) the dev preview
* Uninstall the app
* Open the app in the [Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard)
* Open local and mobile previews of your app and extensions

***

## Develop and test apps as a team

Because changes are isolated to a single dev store, app development teams can safely share a single development instance of an app. The recommended approach for app development teams is:

### Step 1: Create a shared development app instance

If necessary, [create a development instance and configuration file](https://shopify.dev/docs/apps/build/cli-for-apps/manage-app-config-files#test-your-app-functionality) for your app using [`app config link`](https://shopify.dev/docs/api/shopify-cli/app/app-config-link). This development instance will be shared by all team members.

**Note:**

For safety, Shopify recommends that the default `shopify.app.toml` file is used for your development instance.

### Step 2: Onboard individual team members

As a team member, you should:

1. Create your own dev store in the Dev Dashboard.

   **Note:**

   The `app dev` command will push configuration and extension changes to your chosen dev store. It's important to have your own store, so that you can work in isolation from other team members.

2. If necessary, switch to the development configuration of your app with [`app config use`](https://shopify.dev/docs/api/shopify-cli/app/app-config-use).

3. Run `app dev` and choose your dev store:

   ## Terminal

   ```terminal
   shopify app dev
   ```

***