Unified UI Extensions: API versioning, new config, and new target names #1161
Replies: 4 comments 1 reply
-
Migrating existing extensions to the unified format and API versioning
Before you get started, make sure both your The main changes you will need to make will be to your configuration file ( Next, We will be changing a few of the fields you currently use to configure a UI extension:
There are also two new mandatory fields in your configuration file:
If you your extension configuration file had the following contents: # extensions/my-extension/shopify.ui.extension.toml
type = "checkout_ui_extension"
name = "My Extension"
extension_points = [
'Checkout::Dynamic::Render'
]
[[metafields]]
namespace = "my_namespace"
key = "my_key"
[settings]
[[settings.fields]]
key = "banner_title"
type = "single_line_text_field"
name = "Banner title"
description = "Enter a title for the banner"To adopt the next extension format, you would change its contents to: # extensions/my-extension/shopify.extension.toml
api_version = "2023-07"
[[extensions]]
type = "ui_extension"
name = "My Extension"
# To make it easier for the CLI to detect which extensions are being migrated to the new format,
# you should match the `handle` to the name of the directory containing your extension, and both
# should be the handleized version of your extension’s `name`.
handle = "my-extension"
[[extensions.targeting]]
target = "purchase.checkout.block.render"
module = "./src/index.ts"
[[extensions.metafields]]
namespace = "my_namespace"
key = "my_key"
[extensions.settings]
[[extensions.settings.fields]]
key = "banner_title"
type = "single_line_text_field"
name = "Banner title"
description = "Enter a title for the banner"As you can see, the new In addition to the configuration changes, there are two code changes that will be required as well. We will be moving to a new set of packages for distributing UI extension APIs: In your package.json, replace any {
"dependencies": {
- "@shopify/checkout-ui-extensions": "^0.27.0",
+ "@shopify/ui-extensions": "2023.7.x",
- "@shopify/checkout-ui-extensions-react": "^0.27.0",
+ "@shopify/ui-extensions-react": "2023.7.x",
}
}You will notice that the UI extension packages have a new versioning system. In the new versions, the "major" version number is the API version year (e.g., Lastly, the new format has a slightly different system for registering your code to the target defined in your A basic extension today looks like this: import {extend, Banner} from '@shopify/checkout-ui-extensions';
extend('Checkout::Dynamic::Render', (root, {extensionPoint, i18n}) => {
root.appendChild(
root.createComponent(
Banner,
{title: 'My extension'},
i18n.translate('welcome', {target: extensionPoint}),
),
);
});After the change, it will instead look like this: import {extension, Banner} from '@shopify/ui-extensions/checkout';
export default extension(
'purchase.checkout.block.render',
(root, {extension, i18n}) => {
root.appendChild(
root.createComponent(
Banner,
{title: 'My extension'},
i18n.translate('welcome', {target: extension.target}),
),
);
},
);If you use React, the new format will be a similarly minor change, compared to the code you write today: import {
useApi,
render,
Banner,
useTranslate,
} from '@shopify/checkout-ui-extensions-react';
render('Checkout::Dynamic::Render', () => <Extension />);
function Extension() {
const translate = useTranslate();
const {extensionPoint} = useApi();
return (
<Banner title="luxury-trade-ext">
{translate('welcome', {target: extensionPoint})}
</Banner>
);
}
// Becomes:
import {
reactExtension,
useApi,
Banner,
useTranslate,
} from '@shopify/ui-extensions-react/checkout';
export default reactExtension('Checkout::Dynamic::Render', () => <Extension />);
function Extension() {
const translate = useTranslate();
const {extension} = useApi();
return (
<Banner title="luxury-trade-ext">
{translate('welcome', {target: extension.target})}
</Banner>
);
}New target namesThe following table shows the mapping of legacy target names to the new target names:
Make sure you update the target name both in your extension configuration file (with the |
Beta Was this translation helpful? Give feedback.
-
|
@lemonmade a little concerned after some testing.
I'm pretty sure step 5 would break all existing checkout implementations including settings, no? Am I doing something wrong? This was all done on dev app but seems like deploying the new UI Extension breaks the existing connection to checkout ui? Tomlapi_version = "2023-07"
[[extensions]]
type = "ui_extension"
name = "Payment icons"
handle = "payment-icons"
[[extensions.targeting]]
target = "purchase.checkout.block.render"
module = "./src/index.js"Old Extension
New Extension
|
Beta Was this translation helpful? Give feedback.
-
|
For anyone finding this later, the issue in Gil's case was that his existing extension had a directory name that was not the same as either the Thanks for all the help @gil--! |
Beta Was this translation helpful? Give feedback.
-
|
Hi @lemonmade
What could be the reason? Also I can't see the status column |
Beta Was this translation helpful? Give feedback.
-
|
@lemonmade I found out that a preview works when it's disabled Where is a logic here? :D |
Beta Was this translation helpful? Give feedback.
-
We’re introducing some important changes to the way you write UI extensions. As of Summer Editions 2023, we will be introducing a new
shopify.extension.tomlfile. This file will be used to define the basic configuration for your UI extension, and it is the same format that you will use to define Shopify Functions and other types of extensions. In the future, we’ll use this new "unified" configuration file to give you more flexibility in combining extensions of different types to solve merchant problems.Additionally, UI extensions now have the same API versioning strategy as Shopify Functions, and Shopify’s GraphQL API. New API versions will be released 4 times per year, in January, April, July, and October, and are referenced using identifiers like
2023-07(July, 2023). Each API version is supported for one year, but Shopify always strives to build APIs that will be supported for much longer than that.As part of our first API version, we are introducing one major breaking change for existing extensions: new names for the "targets" you use to define where your extension appears in Shopify. We are introducing these targets (previously referred to as "extension points") to improve consistency about how we talk about extensibility across Shopify, and we feel they are also a lot more understandable than our previous format. A mapping of legacy to new target names is included in the migration guide below.
If you already have a UI extension, you can continue to use the existing "unstable" API until July 2024, including the legacy target names. After that, you will need to migrate your extension to be versioned. New APIs will only be released for the versioned API, so we’d love to have you migrate as soon as possible. We’ll also include a detailed upgrade guide as an additional post in this discussion.
Please let us know if you have any questions, thoughts, or concerns about these updates.
Beta Was this translation helpful? Give feedback.
All reactions