Skip to main content

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 @shopify/ui-extensions 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.

@shopify/retail-ui-extensions and @shopify/retail-ui-extensions-react are deprecated. They are now maintained as part of @shopify/ui-extensions and @shopify/ui-extensions-react. This guide explains how to migrate from the old packages to the new ones.

Minimum CLI Version

Migration requires a minimum CLI version of 3.64.0.

Anchor to setupSetup

  1. Before starting, make sure you have the most up to date version of the Shopify CLI.
  2. Navigate to your package.json in the directory of your UI Extension. You'll need to remove @shopify/retail-ui-extensions or @shopify/retail-ui-extensions-react (whichever you're using).
  3. If you use React, replace your version of react and @types/react (if you use typescript) with version 18 and up. @shopify/ui-extensions-react does not support any version prior to React 18.
  4. Next you'll need to add the new dependencies, @shopify/ui-extensions or @shopify/ui-extensions-react. Consult our changelog to see supported versions. If you are using the @shopify/ui-extensions-react package, you will also need to install @shopify/ui-extensions.

Setup

# 1. Update Shopify CLI
yarn global add @shopify/cli@latest

# 2. Remove the old packages
yarn remove @shopify/retail-ui-extensions*

# 3. Upgrade React
yarn upgrade react@^18.2.0
yarn upgrade @types/react@^18.2.0

# 4. Install the new packages
yarn add @shopify/ui-extensions@2024.4
yarn add @shopify/ui-extensions-react@2024.4

Anchor to code-changesCode changes

  1. Replace imports from @shopify/retail-ui-extensions with @shopify/ui-extensions/point-of-sale. Replace imports from @shopify/retail-ui-extensions-react with @shopify/ui-extensions-react/point-of-sale.
  2. Replace calls to extend with extension and replace calls to render with reactExtension. Move each call to extension and reactExtension to individual files, and export them with an export default statement.

Code changes

// Before
import React from 'react'
import { Tile, useApi, render } from '@shopify/retail-ui-extensions-react'

const SmartGridTile = () => {
const api = useApi<'pos.home.tile.render'>()
return (
<Tile
title="My app"
subtitle="SmartGrid Extension"
onPress={() => {
api.smartGrid.presentModal()
}}
enabled
/>
)
}

render('pos.home.tile.render', () => <SmartGridTile />)

// After
import React from 'react'
import { Tile, useApi, reactExtension } from '@shopify/ui-extensions-react/point-of-sale'

const SmartGridTile = () => {
const api = useApi<'pos.home.tile.render'>()
return (
<Tile
title="My app"
subtitle="SmartGrid Extension"
onPress={() => {
api.action.presentModal()
}}
enabled
/>
)
}

export default reactExtension('pos.home.tile.render', () => <SmartGridTile />)

Anchor to configurationConfiguration

Migrate your shopify.extension.toml file to reflect the new syntax.

  • Specify which api_version you are using at the top of the file (above [[extensions]]). This will let POS know which version of the ui-extensions package you're using.
Note

api_version needs to be declared in a yyyy-mm format. If you are using @shopify/ui-extensions version 2024.4 for example, you must declare your api_version as 2024-04. The patch is irrelevant to api_version.

  • Declare each extension target and file path in shopify.extension.toml

Configuration

shopify.extension.toml

api_version = "2024-04"

[[extensions]]
type = "ui_extension"
name = "my-tutorial-extension"
handle = "my-tutorial-extension"
description = "Tutorial extension!"

[[extensions.targeting]]
module = "./src/Tile.tsx"
target = "pos.home.tile.render"

[[extensions.targeting]]
module = "./src/Modal.tsx"
target = "pos.home.modal.render"

Anchor to validationValidation

Validate your migration by running yarn dev or npm run dev

Anchor to finalizeFinalize the migration

  1. Deploy your app by running npm run deploy.
  2. When prompted to migrate your extension from pos_ui_extension to ui_extension, select "Yes, confirm migration from pos_ui_extension".
  3. Your extension should now deploy as the new ui_extension type.