Upgrading to 2025-10

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

Anchor to typescript-configuration-new-tsconfig.jsonNew tsconfig.json

Anchor to typescript-configuration-old-tsconfig.jsonOld tsconfig.json

New tsconfig.json

tsconfig.json

{

"compilerOptions": {

"jsx": "react-jsx",

"jsxImportSource": "preact",

"target": "ES2020",

"checkJs": true,

"allowJs": true,

"moduleResolution": "node",

"esModuleInterop": true

}

Examples

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',

},

};

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

Upgrading to 2025-10

Anchor to update-api-versionUpdate API version

Examples

shopify.extension.toml

shopify.extension.toml

Anchor to adjust-dependenciesAdjust package dependencies

Examples

New dependencies with Preact

package.json

Anchor to update-typescript-configurationTypeScript Configuration

Examples

New tsconfig.json

tsconfig.json

Anchor to upgrading-shopify-cliUpgrade the Shopifiy CLI

Examples

Support new global shopify object

CLI

Anchor to eslint-configurationOptional ESLint configuration

Examples

.eslintrc.cjs

Default

Anchor to migrate-api-callsMigrate API calls

Examples

New API calls in Preact

Preact

Anchor to migrate-to-polaris-web-componentsMigrate to Polaris web components

Examples

New components in Preact

Preact

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

Anchor to additional-componentsAdditional components