Skip to main content

Upgrading to 2025-10

This guide describes how to upgrade your customer account UI extension to API version 2025-10 and adopt Polaris web components.


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

Shopify.extension.toml

api_version = "2025-10"

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

# Contents of your existing file...

Anchor to adjust-dependenciesAdjust 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

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

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

tsconfig.json

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

Anchor to upgrading-shopify-cliUpgrade 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

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

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

Anchor to eslint-configurationOptional ESLint configuration

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

.eslintrc.cjs

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

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

Preact

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

Anchor to migrate-to-polaris-web-componentsMigrate 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

Preact

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

Anchor to mapping-legacy-components-to-polaris-webMapping Legacy components to Polaris web

Legacy ComponentPolaris Web ComponentMigration Notes
AvatarAvatarAvailable today
ButtonGroupAvailable today
CardSectionAvailable today
CustomerAccountActionCustomerAccountActionAvailable today
ImageGroupImageGroupAvailable today
MenuMenuAvailable today
PagePageAvailable today
ResourceItemRemoved. Use Section

Anchor to additional-componentsAdditional components

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