Skip to main content

Test apps locally

The 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

shopify app dev

Anchor to Overview of ,[object Object]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, such as those based on the React Router app template, it serves your self-hosted 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 for that proxy server.
  • If enabled in your app config, 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 using your app's credentials and access scopes.

Anchor to Clean up the dev previewClean 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 in Shopify admin.

  • Run the app dev clean command:

    Terminal

    shopify app dev clean

Anchor to Reset ,[object Object], configurationReset app dev configuration

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

Terminal

shopify app dev --reset

Anchor to Use the Dev Console to manage dev previewsUse 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 the dev preview
  • Uninstall the app
  • Open the app in the Dev Dashboard
  • Open local and mobile previews of your app and extensions

Anchor to Develop and test apps as a teamDevelop 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:

Anchor to Step 1: Create a shared development app instanceStep 1: Create a shared development app instance

If necessary, create a development instance and configuration file for your app using 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.

Anchor to Step 2: Onboard individual team membersStep 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.

  3. Run app dev and choose your dev store:

    Terminal

    shopify app dev
Was this page helpful?