--- title: Migrate app extensions to Shopify CLI description: >- Move your app's dashboard-managed extensions to Shopify CLI, use CLI-managed app configuration, and add uid identifiers to your extensions. source_url: html: 'https://shopify.dev/docs/apps/build/dev-dashboard/migrate-app-extensions' md: 'https://shopify.dev/docs/apps/build/dev-dashboard/migrate-app-extensions.md' --- # Migrate app extensions to Shopify CLI If your app has extensions that you managed in the Partner Dashboard, then you manage them with Shopify CLI from now on. Complete these steps before your next deploy. Your current installations keep working in the meantime. For everything else that moved from the Partner Dashboard, refer to [Migrate from the Partner Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard/migrate-from-partners). *** ## Update Shopify CLI Update to [the latest version of Shopify CLI](https://shopify.dev/docs/api/shopify-cli#upgrade). *** ## Migrate dashboard-managed extensions **Note:** You can no longer create or manage app extensions in a dashboard. You create and manage extensions with Shopify CLI. ### Extensions affected The following extension types, which were managed in the Partner Dashboard, need to be migrated. Refer to the documentation for each extension type: | Extension type | Description | Documentation | | - | - | - | | **[Admin links](https://shopify.dev/docs/apps/build/admin/admin-links)** | Deep links, app navigation, and custom bulk operations from the Shopify admin | [Create admin link extensions](https://shopify.dev/docs/apps/build/admin/admin-links/create-admin-links) | | **[Flow lifecycle events](https://shopify.dev/docs/apps/build/flow/track-lifecycle-events)** | Flow trigger usage notifications | [About Flow development](https://shopify.dev/docs/apps/build/flow/development) | | **[Flow actions](https://shopify.dev/docs/apps/build/flow/actions)** | Shopify Flow integrations for actions | [Create a Flow action](https://shopify.dev/docs/apps/build/flow/actions/create) | | **[Flow triggers](https://shopify.dev/docs/apps/build/flow/triggers)** | Shopify Flow integrations for triggers | [Create a Flow trigger](https://shopify.dev/docs/apps/build/flow/triggers/create) | | **[Marketing activity extensions](https://shopify.dev/docs/apps/build/marketing/marketing-activities)** | Marketing campaign integrations | [Migrate marketing activity extensions](https://shopify.dev/docs/apps/build/marketing/marketing-activities/migrate-extensions) | *** ## Use CLI-managed app configuration CLI-managed app configuration from your `shopify.app.toml` is always included when you run `shopify app deploy` and `shopify app dev`. Shopify CLI automatically removes the `include_config_on_deploy` property from your `shopify.app.toml` file. If your `shopify.app.toml` isn't up to date with the values in your dashboard, then use [`shopify app config link`](https://shopify.dev/docs/api/shopify-cli/app/app-config-link). **Caution:** If you see unexpected configuration changes when running `shopify app deploy`, then your `shopify.app.toml` might not be up to date with values set in your dashboard. Learn more about [managing app config files](https://shopify.dev/docs/apps/build/cli-for-apps/manage-app-config-files). *** ## Migrate to extension user identifiers All extensions need to include user identifiers in the `uid` field of their `shopify.extension.toml`. When deploying a Shopify app, we need to be able to reliably determine which extensions have been added, updated, and removed from your app. This means that we need to map extension code to our records of your extensions on Shopify. To achieve this, [app extensions](https://shopify.dev/docs/apps/build/app-extensions) are idenitified by extension user identifiers (UIDs) that are set in the `shopify.extension.toml` file. Extension UIDs are unique, source-defined, and app-scoped, so they can be shared across production, staging, and development apps. By default, UIDs are automatically added when you create a new extension using `shopify app extension generate`, or when you run `shopify app deploy`. UIDs are deterministic based on the extension handle, so they will always be the same for extensions with the same app handle value. Non-interactive deploys (`shopify app deploy --allow-updates`) and the `shopify app dev` command fail until you've completed these steps. **Note:** The `uid` is different from the extension identifiers in the `.env` file, which `shopify app deploy` previously generated. After you map `uid` values during `app deploy`, the `.env` extension identifiers are no longer used, and `uid` values can be shared across all copies of your app. ### Create and map `uid` values You need to run a one-time interactive `deploy` to create and map `uid` values: 1. Run [`shopify app deploy`](https://shopify.dev/docs/api/shopify-cli/app/app-deploy) against a code branch that represents the current release of your app. * Shopify CLI generates a new `uid` value for each extension, based on the extension `handle`, and writes it to the `shopify.extension.toml` file. * In the confirmation prompt for the `deploy`, Shopify CLI indicates that all your extensions are `updated`. **Caution:** Removing and adding an extension can result in data loss on installed stores. If you see extensions that are `new` and `removed`, instead of `updated`, then the extension failed to map. [Update the extension `handle` or `.env` environment variable](#how-extensions-are-mapped-to-shopify) to match the extension on Shopify. * Select `Yes` to confirm the deploy and release of the app. * Shopify sets the `uid` values as the identifiers for your extensions. 2. Commit the new `uid` values to your source control. 3. For each additional app instance: 1. Merge the new `uid` values into the appropriate code branch for the app instance. 2. Run [`shopify app deploy --config `](https://shopify.dev/docs/api/shopify-cli/app/app-deploy#flags-propertydetail-cconfigvalue) to map the same `uid` values to the app instance. ### How extensions are mapped to Shopify During `uid` mapping, Shopify CLI uses the following logic to map extensions to Shopify: 1. Identify the active `.env` file for the current app configuration. For example: * If `shopify.app.toml` is active, then `.env` is used. * If `shopify.app.prod.toml` is active, then `.env.prod` is used. 2. Look for an extension identifier in the `.env` file for the current app configuration, based on the extension `handle`. The environment variable is named `SHOPIFY__ID`. For example: * If the extension `handle` is `discount`, then the environment variable is `SHOPIFY_DISCOUNT_ID`. * If the extension `handle` is `product-reviews`, then the environment variable is `SHOPIFY_PRODUCT_REVIEWS_ID`. 3. If an extension identifier isn't found in `.env`, then match on the extension `type` and `handle`. 4. If no match is found, then Shopify CLI prompts for any potential matches. **Note:** Before the Dev Dashboard migration, the `shopify app deploy` command populated these `.env` files. If an `.env` file isn't available for your app configuration, then update extension handles to match their values on Shopify. After this initial `deploy`, Shopify CLI uses only the `uid` value to determine whether it creates, updates, or deletes an extension. *** ## Next steps * [Learn about app configuration](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration) with Shopify CLI. * [Monitor app performance](https://shopify.dev/docs/apps/build/dev-dashboard/monitoring-and-logs) to find the metrics and logs that replaced the Partner Dashboard's app insights. * [Migrate from the Partner Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard/migrate-from-partners) to find everything else that moved. ***