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

***