---
title: Upgrading to 2025-10
description: >
  This guide describes how to upgrade your customer account UI extension to API
  version `2025-10` and adopt [Polaris](/beta/next-gen-dev-platform/polaris) web
  components.
api_version: 2025-10
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/upgrading-to-2025-10
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/upgrading-to-2025-10.md
---

# Upgrading to 2025-10

This guide describes how to upgrade your customer account 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

##### Previous dependencies with React

##### Previous dependencies with JavaScript

## 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 JavaScript

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

##### Old tsconfig.json

## New tsconfig.json

## tsconfig.json

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

## Old tsconfig.json

## tsconfig.json

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

***

## Upgrade the Shopifiy CLI

The new CLI adds supoort 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

## CLI

```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 or React hook, access them from the global `shopify` object. Here's an example of migrating the Cart Line Target API call.

##### New API calls in Preact

##### Previous API calls in React

##### Previous API calls in JavaScript

## 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-text>Line item title: {shopify.target.value.merchandise.title}</s-text>
  );
}
```

## Previous API calls in React

## React

```tsx
import {
  reactExtension,
  Text,
  useCartLineTarget,
} from '@shopify/ui-extensions-react/customer-account';


export default reactExtension(
  'customer-account.order-status.cart-line-item.render-after',
  () => <Extension />,
);


function Extension() {
  const {
    merchandise: {title},
  } = useCartLineTarget();


  return <Text>Line item title: {title}</Text>;
}
```

## Previous API calls in JavaScript

## JavaScript

```tsx
import {extension} from '@shopify/ui-extensions/customer-account';


export default extension(
  'customer-account.order-status.cart-line-item.render-after',
  (root, {target}) => {
    const text = root.createText(`Line item title: ${target.current.title}`);
    root.appendChild(text);


    target.subscribe((updatedTarget) => {
      text.updateText(`Line item title: ${updatedTarget.title}`);
    });
  },
);
```

***

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

##### Previous components in React

##### Previous components in JavaScript

## New components 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-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

## React

```tsx
import {
  reactExtension,
  InlineStack,
  TextField,
  Button,
} from '@shopify/ui-extensions-react/customer-account';


export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);


function Extension() {
  return (
    <InlineStack>
      <TextField label="Gift message" />
      <Button>Save</Button>
    </InlineStack>
  );
}
```

## Previous components in JavaScript

## JavaScript

```tsx
import {
  extension,
  InlineStack,
  TextField,
  Button,
} from '@shopify/ui-extensions/customer-account';


export default extension(
  'customer-account.order-status.block.render',
  (root, _api) => {
    root.replaceChildren(
      root.createComponent(InlineStack, {}, [
        root.createComponent(TextField, {
          label: 'Gift message',
        }),
        root.createComponent(Button, {}, 'Save'),
      ]),
    );
  },
);
```

***

## Mapping Legacy components to Polaris web

| **Legacy Component** | **Polaris Web Component** | **Migration Notes** |
| - | - | - |
| `Avatar` | [Avatar](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/media/avatar) | Available today |
| | [ButtonGroup](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/actions/buttongroup) | Available today |
| `Card` | [Section](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/structure/section) | Available today |
| `CustomerAccountAction` | [CustomerAccountAction](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/actions/customeraccountaction) | Available today |
| `ImageGroup` | [ImageGroup](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/media/imagegroup) | Available today |
| `Menu` | [Menu](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/actions/menu) | Available today |
| `Page` | [Page](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/structure/page) | Available today |
| `ResourceItem` | | Removed. Use [Section](https://shopify.dev/api/customer-account-ui-extensions/polaris-web-components/structure/section) |

***

## Additional components

In addition to the components above, you can also use Polaris web components in the Checkout library to build customer account UI extensions.

[More Polaris web components - Checkout components](https://shopify.dev/docs/api/checkout-ui-extensions/polaris-web-components)

***