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.

Choose a version:

Anchor to update-api-versionUpdate API version

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

Examples

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.

Anchor to adjust-package-dependencies-new-dependencies-with-preactNew dependencies with Preact

Anchor to adjust-package-dependencies-previous-dependencies-with-reactPrevious dependencies with React

Anchor to adjust-package-dependencies-previous-dependencies-with-javascriptPrevious dependencies with JavaScript

New dependencies with Preact

package.json

{

"dependencies": {

"preact": "^10.10.x",

"@preact/signals": "^2.3.x",

"@shopify/ui-extensions": "2025.10.x"

}

Anchor to update-typescript-configurationUpdate TypeScript Configuration

Update your extension config at a path like extensions/{extension-name}/tsconfig.json. You do not need to change your app's root tsconfig.json file.

Skip if not using TypeScript

These steps make TypeScript aware of the new global shopify object. Skip this step if your app was not built using TypeScript.

Update your extension's tsconfig.json

{

"compilerOptions": {

"jsx": "react-jsx",

"jsxImportSource": "preact",

"target": "ES2020",

"checkJs": true,

"allowJs": true,

"moduleResolution": "node",

"esModuleInterop": true

}

Examples

Update your extension's tsconfig.json

New tsconfig.json

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

Old tsconfig.json

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

Anchor to generate-type-definitionsGenerate type definition file

These commands generate a shopify.d.ts file in your extension directory.

Skip if not using TypeScript

These steps make TypeScript aware of the new global shopify object. Skip this step if your app was not built using TypeScript.

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 migrate-api-callsMigrate 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.

Anchor to migrate-api-calls-new-api-calls-in-preactNew API calls in Preact

Anchor to migrate-api-calls-previous-api-calls-in-reactPrevious API calls in React

Anchor to migrate-api-calls-previous-api-calls-in-javascriptPrevious API calls in JavaScript

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>

);

}

Examples

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.

Anchor to migrate-to-polaris-web-components-new-components-in-preactNew components in Preact

Anchor to migrate-to-polaris-web-components-previous-components-in-reactPrevious components in React

Anchor to migrate-to-polaris-web-components-previous-components-in-javascriptPrevious components in JavaScript

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>

);

}

Examples

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 Component	Polaris Web Component	Migration Notes
`Avatar`	Avatar	Available today
	ButtonGroup	Available today
`Card`	Section	Available today
`CustomerAccountAction`	CustomerAccountAction	Available today
`ImageGroup`	ImageGroup	Available today
`Menu`	Menu	Available today
`Page`	Page	Available today
`ResourceItem`		Removed. 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.

More Polaris web componentsCheckout components