---
title: Upgrading to 2025-10
description: >
  This guide describes how to upgrade your point-of-sale UI extension to API
  version `2025-10` and adopt [Polaris](/beta/next-gen-dev-platform/polaris) web
  components.
source_url:
  html: 'https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10'
  md: 'https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md'
---

ExpandOn this page

* [Update API version](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#update-api-version)
* [Adjust package dependencies](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#adjust-package-dependencies)
* [Type​Script configuration](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#typescript-configuration)
* [Upgrade the Shopify CLI](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#upgrade-the-shopify-cli)
* [Optional ESLint configuration](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#optional-eslint-configuration)
* [Migrate API calls](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#migrate-api-calls)
* [Migrate hooks](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#migrate-hooks)
* [Migrate to Polaris web components](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#migrate-to-polaris-web-components)
* [Polaris web components mapping](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#polaris-web-components-mapping)

# Upgrading to 2025-10

This guide describes how to upgrade your point-of-sale UI extension to API version `2025-10` and adopt [Polaris](https://shopify.dev/beta/next-gen-dev-platform/polaris) web components.

***

## Update API version

Set the API version to `2025-10` in `shopify.extension.toml` to use Polaris web components.

### shopify.​extension.​toml

```toml
api_version = "2025-10"


[[extensions]]
name = "your-extension"
handle = "your-extension"
type = "ui_extension"


# Contents of your existing file...
```

***

## Adjust package dependencies

As of `2025-10`, Shopify recommends Preact for UI extensions. Update the dependencies in your `package.json` file and re-install.

### New dependencies with Preact

##### package.​json

```json
{
  "dependencies": {
    "preact": "^10.10.x",
    "@preact/signals": "^2.3.x",
    "@shopify/ui-extensions": "2025.10.x"
  }
}
```

### Previous dependencies with React

##### package.​json

```json
{
  "dependencies": {
    "react": "^18.0.0",
    "@shopify/ui-extensions": "2025.4.x",
    "@shopify/ui-extensions-react": "2025.4.x",
    "react-reconciler": "0.29.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.0"
  }
}
```

### Previous dependencies with Java​Script

##### package.​json

```json
{
  "dependencies": {
    "@shopify/ui-extensions": "2025.4.x"
  }
}
```

***

## Type​Script configuration

Get full IntelliSense and auto-complete support by adding a config file for your extension at `extensions/{extension-name}/tsconfig.json`. You do **not** need to change your app's root `tsconfig.json` file.

### New tsconfig.​json

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
    "target": "ES2020",
    "checkJs": true,
    "allowJs": true,
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}
```

### Old tsconfig.​json

```json
{
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["./src"]
}
```

***

## Upgrade the Shopify CLI

The new CLI adds support for building 2025-10 extensions.

The `shopify app dev` command runs your app and also generates a `shopify.d.ts` file in your extension directory, adding support for the new global `shopify` object.

### Support new global shopify object

```bash
# Upgrade to latest version of the CLI
npm install -g @shopify/cli


# Run the app to generate the type definition file
shopify app dev
```

***

## Optional ESLint configuration

If your app is using ESLint, update your configuration to include the new global `shopify` object.

### .​eslintrc.​cjs

```js
module.exports = {
  globals: {
    shopify: 'readonly',
  },
};
```

***

## Migrate API calls

Instead of accessing APIs from a callback parameter, access them from the global `shopify` object. Here's an example of migrating API calls.

### New API calls in Preact

##### Preact

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';


export default function extension() {
  render(<Extension />, document.body);
}


function Extension() {
  return <s-button onClick={onButtonClick}>Print</s-button>;
}


async function onButtonClick() {
  await shopify.print.print('documents/test-print');
  console.log('print completed');
}
```

### Previous API calls in React

##### React

```tsx
import {
  reactExtension,
  Button,
  useApi,
} from '@shopify/ui-extensions-react/point-of-sale';


export default reactExtension('pos.home.modal.render', () => <Extension />);


function Extension() {
  const api = useApi();


  async function onButtonClick(isChecked) {
    await api.print.print('documents/test-print');
    console.log('print completed');
  }


  return <Button onPress={onButtonClick} title="Print" />;
}
```

### Previous API calls in Java​Script

##### Java​Script

```ts
import {extension, Button} from '@shopify/ui-extensions/point-of-sale';


export default extension('pos.home.modal.render', (root, api) => {
  async function onButtonClick() {
    await api.print.print('documents/test-print');
    console.log('print completed');
  }


  root.replaceChildren(
    root.createComponent(Button, {
      onPress: onButtonClick,
      title: 'Print',
    }),
  );
});
```

***

## Migrate hooks

If you had previously been using React hooks, import those same hooks from a new Preact-specific package. Here's an example of migrating hooks.

### New hooks in Preact

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';


export default function extension() {
  render(<ConnectivityStatus />, document.body);
}


function ConnectivityStatus() {
  const [isConnected, setIsConnected] = useState(
    shopify.connectivity.current.value.internetConnected === 'Connected',
  );


  useEffect(() => {
    const unsubscribe = shopify.connectivity.current.subscribe(
      (newConnectivity) => {
        setIsConnected(newConnectivity.internetConnected === 'Connected');
      },
    );
    return unsubscribe;
  }, []);


  return (
    <s-text tone={isConnected ? 'success' : 'warning'}>
      Status: {isConnected ? 'Online' : 'Offline'}
    </s-text>
  );
}
```

### Previous hooks in React

```tsx
import React from 'react';
import {
  Text,
  useConnectivitySubscription,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';


const ConnectivityStatus = () => {
  const connectivity = useConnectivitySubscription();
  const isConnected = connectivity.internetConnected === 'Connected';


  return (
    <Text color={isConnected ? 'TextSuccess' : 'TextWarning'}>
      Status: {isConnected ? 'Online' : 'Offline'}
    </Text>
  );
};


export default reactExtension('pos.home.modal.render', () => (
  <ConnectivityStatus />
));
```

***

## Migrate to Polaris web components

Polaris web components are exposed as custom HTML elements. Update your React or JavaScript components to custom elements.

### New components in Preact

```tsx
/* eslint-disable react/self-closing-comp */
import '@shopify/ui-extensions/preact';
import {render} from 'preact';


export default function extension() {
  render(<Extension />, document.body);
}


function Extension() {
  return (
    <s-stack direction="inline" gap="base">
      <s-text-field label="Gift message"></s-text-field>
      <s-button variant="primary">Save</s-button>
    </s-stack>
  );
}
```

### Previous components in React

```tsx
import {
  reactExtension,
  Stack,
  TextField,
  Button,
} from '@shopify/ui-extensions-react/point-of-sale';


export default reactExtension('pos.home.modal.render', () => <Extension />);


function Extension() {
  return (
    <Stack direction="inline" gap="200">
      <TextField label="Gift message" />
      <Button title="Save" variant="primary" />
    </Stack>
  );
}
```

### Previous components in Java​Script

```ts
import {
  extension,
  Stack,
  TextField,
  Button,
} from '@shopify/ui-extensions/point-of-sale';


export default extension('pos.home.modal.render', (root, _api) => {
  root.replaceChildren(
    root.createComponent(Stack, {direction: 'inline', gap: '200'}, [
      root.createComponent(TextField, {
        label: 'Gift message',
      }),
      root.createComponent(Button, {title: 'Save', variant: 'primary'}),
    ]),
  );
});
```

***

## Polaris web components mapping

| **Legacy Component** | **Polaris Web Component** | **Migration Notes** |
| - | - | - |
| `Badge` | [`Badge`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentstitles-and-text/badge) | Available |
| `Banner` | [`Banner`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsfeedback/banner) | Available |
| `Box` | [`Box`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsstructure/box) | Available |
| `Button` | [`Button`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsactions/button) | Available |
| `CameraScanner` | `CameraScanner` | Coming soon |
| `DateField` | [`DateField`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/datefield) | Available |
| `DatePicker` | [`DatePicker`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/datepicker) | Available |
| `DatePicker` | [`DateSpinner`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/datespinner) | Available, Replaces `DatePicker.inputMode="spinner"` |
| `Dialog` | [`Modal`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsstructure/modal) | Available |
| `EmailField` | [`EmailField`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/emailfield) | Available |
| `Heading` | [`Heading`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentstitles-and-text/heading) | Available |
| `Icon` | [`Icon`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsmedia/icon) | Available, more icons coming soon. |
| `Image` | [`Image`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsmedia/image) | Available |
| `List` | VirtualizedList | Coming soon |
| `Navigator` | | Removed. |
| `NumberField` | [`NumberField`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/numberfield) | Available |
| `PinPad` | | Coming soon |
| `POSBlock` | [`POSBlock`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsstructure/posblock) | Available |
| `POSBlockRow` | | Replaced by `POSBlock` |
| `POSReceiptBlock` | | Replaced by `POSBlock` |
| `PrintPreview` | `DocumentPreview` | Coming soon |
| `QRCode` | `QRCode` | Coming soon |
| `RadioButtonList` | [`ChoiceList`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/choicelist) | Available |
| `Screen` | [`Page`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsstructure/page) | Available |
| `ScrollView` | [`ScrollBox`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsstructure/scrollbox) | Available |
| `SearchBar` | [`SearchField`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/searchfield) | Available |
| `Section` | [`Section`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsstructure/section) | Available |
| `SectionHeader` | | Use `Section.heading` |
| `SegmentedControl` | `Tabs`/`Tab` | Coming soon |
| `Selectable` | [`Clickable`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsactions/clickable) | Available |
| `Stack` | [`Stack`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsstructure/stack) | Available |
| `Stepper` | [`NumberField`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/numberfield) | Use `NumberField` with stepper controls |
| `Text` | [`Text`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentstitles-and-text/text) | Available |
| `TextArea` | [`TextArea`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/textarea) | Available |
| `TextField` | [`TextField`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/textfield) | Available |
| `Tile` | [`Tile`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsactions/tile) | Available |
| `TimeField` | [`TimeField`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/timefield) | Available |
| `TimePicker` | [`TimePicker`](https://shopify.dev/docs/api/pos-ui-extensions/polaris-web-componentsforms/timepicker) | Available |

***

* [Update API version](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#update-api-version)
* [Adjust package dependencies](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#adjust-package-dependencies)
* [Type​Script configuration](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#typescript-configuration)
* [Upgrade the Shopify CLI](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#upgrade-the-shopify-cli)
* [Optional ESLint configuration](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#optional-eslint-configuration)
* [Migrate API calls](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#migrate-api-calls)
* [Migrate hooks](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#migrate-hooks)
* [Migrate to Polaris web components](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#migrate-to-polaris-web-components)
* [Polaris web components mapping](https://shopify.dev/docs/apps/build/pos/upgrading-to-2025-10.md#polaris-web-components-mapping)