---
title: Migrating
description: Migrate your POS UI Extension to use the latest unified ui-extension package.
api_version: 2024-10
api_name: pos-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/pos-ui-extensions/2024-10/migrating
  md: https://shopify.dev/docs/api/pos-ui-extensions/2024-10/migrating.md
---

# Migrating

Migrate your POS UI Extension to use the latest unified ui-extension package.

## Overview

POS UI Extensions are moving to the newer `@shopify/ui-extensions` package, shared with [Checkout UI Extensions](https://shopify.dev/docs/api/checkout-ui-extensions) and [Admin UI Extensions](https://shopify.dev/docs/api/admin-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.

## Setup

1. Before starting, make sure you have the most up to date version of the [Shopify CLI](https://shopify.dev/docs/api/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](https://shopify.dev/docs/api/pos-ui-extensions/unstable/versions) to see supported versions. If you are using the `@shopify/ui-extensions-react` package, you will also need to install `@shopify/ui-extensions`.

### Examples

* #### Setup

  ##### yarn

  ```bash
  # 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.10
  yarn add @shopify/ui-extensions-react@2024.10
  ```

  ##### npm

  ```bash
  # 1. Update Shopify CLI
  npm i -g @shopify/cli@latest

  # 2. Remove the old packages
  npm uninstall @shopify/retail-ui-extensions*

  # 3. Upgrade React
  npm update react@^18.2.0
  npm update @types/react@^18.2.0

  # 4. Install the new packages
  npm install @shopify/ui-extensions@2024.10
  npm install @shopify/ui-extensions-react@2024.10
  ```

## Code 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.

### Examples

* #### Code changes

  ##### React

  ```tsx
  // 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 />)
  ```

  ##### TS

  ```ts
  // Before
  import {extend, Tile} from '@shopify/retail-ui-extensions';

  extend('pos.home.tile.render', (root, api) => {
    const tile = root.createComponent(Tile, {
      title: 'My app',
      subtitle: 'SmartGrid Extension',
      onPress: () => api.smartGrid.presentModal(),
      enabled: true,
    });

    root.append(tile);
    root.mount();
  });

  // After
  import {extension, Tile} from '@shopify/ui-extensions/point-of-sale';

  export default extension('pos.home.tile.render', (root, api) => {
    const tile = root.createComponent(Tile, {
      title: 'My app',
      subtitle: 'SmartGrid Extension',
      onPress: () => api.action.presentModal(),
      enabled: true,
    });

    root.append(tile);
  });
  ```

## Configuration

Migrate your `shopify.extension.toml` file to reflect the [new syntax](https://shopify.dev/docs/apps/structure/app-extensions/configuration#how-it-works).

* 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.10` for example, you must declare your `api_version` as 2024-10. The patch is irrelevant to `api_version`.

* Declare each extension target and file path in `shopify.extension.toml`

### Examples

* #### Configuration

  ##### shopify.extension.toml

  ```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"
  ```

## Validation

Validate your migration by running `yarn dev` or `npm run dev`

## Finalize 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.