Hello Shopify app developers! As we roll out migrations from Partners to the Next-gen Dev Platform, those of you with extensions in your apps should familiarize yourselves with the necessary migration steps. Among these is the migration to extension user identifiers, or UIDs, in the shopify.extension.toml. These new identifiers change how your local extensions are mapped to their records on Shopify, so it’s worth double-clicking on what is changing here, and why.
Why are we making this change?
During shopify app deploy, we need to determine which extensions have been added, updated, and removed. This means that we need to map your extension code, to our records of your extensions on Shopify:
Prior to the Dev Platform, this matching process was… complicated. It was reliable if you maintained the .env file generated by app deploy for each copy of your app (dev/staging/prod), or if you never changed an extension handle. But otherwise there was always the risk of a mismatch, and for accidentally deleting extensions (especially with the --force flag). Accidental deletion of an extension also means deleting any activations of those extensions on installed stores. 
A Shopify colleague diagrammed this labyrinthine process for me:
With UIDs on the Next-gen Dev Platform, it’s now this:
That’s it! This new process makes deployments simpler and more reliable.
How do user identifiers work?
The user identifiers appear in the shopify.extension.toml as a new uid property on each extension:
[[extensions]]
name = "checkout-ui"
handle = "checkout-ui"
uid = "fddfc370-27c7-c30f-4ee0-a927194e2accadefd40c"
type = "ui_extension"
These UIDs are app-scoped, and source-defined – so unlike the global .env identifiers, they can be the same when deploying any linked copy of your app. There’s no need to maintain identifier values in .env files or CI/CD configuration, no need to worry about changes to extension handles, or really to think about these identifiers at all. During migration they will be generated for you, as well as when you create new extensions.
If you ever do need to reference the UID value (munged git merge perhaps?), you can find it in your app Versions on the Dev Dashboard.
It’s also worth noting that by default, the UID is deterministically set in your toml based on the extension handle, so it will always be the same for extensions with the same handle value.
But don’t use them with function activation
A temporary source of confusion is that these UIDs are different from the global extension identifiers previously found in the .env files and the Partner Dashboard. In addition to their previous role in mapping extensions during deploy, these global identifiers are used to activate function extensions. We have a planned update to switch to the function handle for referencing functions in the Admin API. Meanwhile you can still use the shopifyFunctions query to get the needed ID.
Our goal is for these global identifiers to go away entirely, so that the uid is the app-scoped unique ID for the extension, and the handle is the developer-friendly identifier in our APIs and user interfaces.
Migrate your app to unlock simpler deploys
The migration of your apps to the Next-gen Dev Platform is a straightforward process, but we know any migration can bring a level of concern. However by migrating to user identifiers, you unlock a more straightforward and reliable deployment process for your apps, in addition to all the other features of the Next-gen Dev Platform.
