Migrating
Migrate your POS UI Extension to use the latest unified ui-extension package.
Anchor to overviewOverview
POS UI Extensions are moving to the newer package, shared with Checkout UI Extensions and Admin UI Extensions. This will allow your extensions to use the same package regardless of the surface they extend, and for a single extension to implement multiple targets across different surfaces of Shopify more easily.
and
are deprecated. They are now maintained as part of
and
. This guide explains how to migrate from the old packages to the new ones.
Migration requires a minimum CLI version of 3.64.0.
Anchor to setupSetup
- Before starting, make sure you have the most up to date version of the Shopify CLI.
- Navigate to your
package.json
in the directory of your UI Extension. You'll need to removeor
(whichever you're using).
- If you use React, replace your version of
react
and(if you use typescript) with version 18 and up.
does not support any version prior to React 18.
- Next you'll need to add the new dependencies,
or
. Consult our changelog to see supported versions. If you are using the
package, you will also need to install
.
Setup
Anchor to code-changesCode changes
- Replace imports from
with
. Replace imports from
with
.
- Replace calls to
extend
withextension
and replace calls torender
with. Move each call to
extension
andto individual files, and export them with an
export default
statement.
Code changes
Anchor to configurationConfiguration
Migrate your shopify.extension.toml
file to reflect the new syntax.
- Specify which
you are using at the top of the file (above
[[extensions]]
). This will let POS know which version of theui-extensions
package you're using.
needs to be declared in a
yyyy-mm
format. If you are using version
2025.4
for example, you must declare your as 2025-04. The patch is irrelevant to
.
- Declare each extension target and file path in
shopify.extension.toml
Configuration
shopify.extension.toml
Anchor to validationValidation
Validate your migration by running yarn dev
or npm run dev
Anchor to finalizeFinalize the migration
- Deploy your app by running
npm run deploy
. - When prompted to migrate your extension from
to
, select "Yes, confirm migration from pos_ui_extension".
- Your extension should now deploy as the new ui_extension type.