--- title: Upgrading to 2025-10 description: > This guide describes how to upgrade your admin UI extension to API version `2025-10` and adopt web components. source_url: html: 'https://shopify.dev/docs/apps/build/admin/upgrading-to-2025-10' md: 'https://shopify.dev/docs/apps/build/admin/upgrading-to-2025-10.md' --- # Upgrading to 2025-10 This guide describes how to upgrade your admin UI extension to API version `2025-10` and adopt [web components](https://shopify.dev/docs/api/admin-extensions/latest/web-components) from Polaris, Shopify's unified system for building app interfaces. Version 2025-07 is the last API version to support React-based UI components. Web components replace them with native UI elements that offer built-in accessibility, better performance, and consistent styling — so your extension looks and behaves like the rest of the Shopify admin. *** ## Update API version Set the API version to `2025-10` in `shopify.extension.toml` to use web components. ## shopify.extension.toml ```toml api_version = "2025-10" [[extensions]] name = "your-extension" handle = "your-extension" type = "ui_extension" uid = "ab22fe63-a741-cbc6-90c1-fbcf94a84426b9cbbe1f" # 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 ## 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 don't need to change your app's root `tsconfig.json` file. ## New tsconfig.json ```json { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "preact", "target": "ES2020", "checkJs": true, "allowJs": true, "moduleResolution": "node", "esModuleInterop": true } } ``` ## Old tsconfig.json ```json { "compilerOptions": { "jsx": "react-jsx" }, "include": ["./src"] } ``` *** ## Upgrade the Shopify CLI The new CLI adds support 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 ```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 uses 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 API calls for an admin block. ## New API calls in Preact ```tsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const productId = shopify.data.selected?.[0]?.id; return ( Product ID: {productId} ); } ``` ## Previous API calls in React ```tsx import { reactExtension, useApi, AdminBlock, Text, } from '@shopify/ui-extensions-react/admin'; export default reactExtension( 'admin.product-details.block.render', () => , ); function Extension() { const {data} = useApi(); const productId = data.selected?.[0]?.id; return ( Product ID: {productId} ); } ``` ## Previous API calls in JavaScript ```ts import {extension, AdminBlock, Text} from '@shopify/ui-extensions/admin'; export default extension( 'admin.product-details.block.render', (root, api) => { const productId = api.data.selected?.[0]?.id; const adminBlock = root.createComponent( AdminBlock, {title: 'Product information'}, [root.createComponent(Text, {}, `Product ID: ${productId}`)], ); root.appendChild(adminBlock); root.mount(); }, ); ``` *** ## Migrate hooks If you were previously using React hooks, import those same hooks from a Preact-specific package. Here's an example of migrating hooks for an admin action. ## New hooks in Preact ```tsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useState} from 'preact/hooks'; export default function extension() { render(, document.body); } function Extension() { const [title, setTitle] = useState(''); async function handleSubmit() { const productId = shopify.data.selected?.[0]?.id; await fetch('shopify:admin/api/graphql.json', { method: 'POST', body: JSON.stringify({ query: `mutation SetMetafield($input: [MetafieldsSetInput!]!) { metafieldsSet(metafields: $input) { metafields { id } } }`, variables: { input: [{ ownerId: productId, namespace: 'my-app', key: 'title', type: 'single_line_text_field', value: title, }], }, }), }); shopify.close(); } return ( setTitle(e.target.value)} /> Save ); } ``` ## Previous hooks in React ```tsx import React, {useState} from 'react'; import { reactExtension, useApi, AdminAction, Button, TextField, } from '@shopify/ui-extensions-react/admin'; export default reactExtension( 'admin.product-details.action.render', () => , ); function Extension() { const {close, data, query} = useApi(); const [title, setTitle] = useState(''); async function handleSubmit() { const productId = data.selected?.[0]?.id; await query( `mutation SetMetafield($input: [MetafieldsSetInput!]!) { metafieldsSet(metafields: $input) { metafields { id } } }`, { variables: { input: [{ ownerId: productId, namespace: 'my-app', key: 'title', type: 'single_line_text_field', value: title, }], }, }, ); close(); } return ( Save}> ); } ``` *** ## Migrate to web components Web components are exposed as custom HTML elements. Update your React components to custom elements. ## New components in Preact ```tsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { return ( Update ); } ``` ## Previous components in React ```tsx import { reactExtension, AdminBlock, BlockStack, TextField, Button, } from '@shopify/ui-extensions-react/admin'; export default reactExtension( 'admin.order-details.block.render', () => , ); function Extension() { return (