Polaris Web Components 2.0 is now available on the CDN's stable channel. It's the first major release since the CDN adopted semantic versioning. However,it won't switch over automatically, so you need to change your script tag to polaris-2.js .
polaris-2.js and polaris-2.0.js — 2.0 is served from both URLs.
A version built to match the redesigned admin's frame, navigation, and appearance.
polaris.js / polaris-1.js continues to serve 1.1. To use 2.0, update your script tag yourself.
polaris-2.js tracks the latest 2.x release, whilepolaris-2.0.js is pinned to 2.0.polaris.js is explicitly stated tonever move to 2.x.
| URL | Version served today | On future 2.x releases | Best for |
|---|---|---|---|
polaris.js |
1.1 | Willnevermove to 2.x | Apps not migrating right away |
polaris-1.js |
1.1 | Not stated (it says 1.1 will continue to be served) | Apps that want to stay on 1.x |
polaris-2.js |
2.0 | Follows later 2.x releases | The officially recommended update target |
polaris-2.0.js |
2.0 | Stays pinned to 2.0 | Apps that want to stay on 2.0 without picking up later 2.x releases |
polaris.js / polaris-1.js to polaris-2.js .
@shopify/polaris-types@^2.0.0 — install it.
If you don't want later 2.x releases, use polaris-2.0.js .
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.js"></script>
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.0.js"></script><script src="https://cdn.shopify.com/shopifycloud/polaris-2.0.js"></script>polarisUrl is set in two placesAppProvider and shopifyApp server config: set polarisUrl in both, with matching values.@shopify/shopify-app-react-router 2.1.0 or lateris required.
npm install @shopify/polaris-types@^2.0.0The article only says to install @shopify/polaris-types@^2.0.0 . The above is an npm example (any package manager works).
Existing apps stay on 1.1 unless you change anything. Nothing breaks on its own, butyou need to switch over yourself to match the new admin look.
polaris.js is not "latest"The name suggests it points to the newest version, but itwill never move to 2.x. Drop the assumption that using polaris.js keeps you on the latest.
polaris-2.js tracks later 2.x releases;polaris-2.0.js is pinned to 2.0. Pin if you want to stay on a tested version; track if you want updates automatically.
AppProvider and the server-side shopifyApp 's polarisUrl must be set to the same value. Don't change only one of them.@shopify/shopify-app-react-router Requires 2.1.0 or later.
In TypeScript projects, install @shopify/polaris-types@^2.0.0 . Keep the CDN version and the type definitions version aligned. The article doesn't detail the changes, so read "Update your app for Polaris 2" and "Versioning for web components" alongside it.
polaris-2.js , and in TypeScript projects update to @shopify/polaris-types@^2.0.0 .polaris-2.0.js as the pinned version and verify on 2.0 → when later 2.x releases ship, test them before bumping the URL.polaris-2.js, apps that should stay pinned use polaris-2.0.js— decide the policy per app and document it in the README.@shopify/shopify-app-react-router at 2.1.0 or later → ② AppProvider and shopifyApp : polarisUrl set to the same value → ③ type definitions set to ^2.0.0 — turn these three checks into a checklist.polarisUrl — define it once as an environment variable or shared constant and reference it from both places to avoid mismatched values.