Skip to main content

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.

Anchor to Update Shopify CLIUpdate Shopify CLI

Update to the latest version of Shopify CLI.

Anchor to Migrate dashboard-managed extensionsMigrate dashboard-managed extensions

Note

You can no longer create or manage app extensions in a dashboard. You create and manage extensions with Shopify CLI.

Anchor to Extensions affectedExtensions 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 typeDescriptionDocumentation
Admin linksDeep links, app navigation, and custom bulk operations from the Shopify adminCreate admin link extensions
Flow lifecycle eventsFlow trigger usage notificationsAbout Flow development
Flow actionsShopify Flow integrations for actionsCreate a Flow action
Flow triggersShopify Flow integrations for triggersCreate a Flow trigger
Marketing activity extensionsMarketing campaign integrationsMigrate marketing activity extensions

Anchor to Use CLI-managed app configurationUse 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.

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.

Anchor to Migrate to extension user identifiersMigrate 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 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.

Anchor to Create and map ,[object Object], valuesCreate and map uid values

You need to run a one-time interactive deploy to create and map uid values:

  1. Run shopify 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 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 <name> to map the same uid values to the app instance.

Anchor to How extensions are mapped to ShopifyHow 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_<HANDLE_SNAKE_CASE>_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.

Anchor to Next stepsNext steps

Was this page helpful?