The versioning scheme for Polaris Web Components loaded from the CDN is moving to semver. Backward-compatible improvements still arrive automatically, but developers now explicitly choose when to take on breaking changes (majors). No immediate action is required for existing apps.
Bug fixes, accessibility and performance improvements, visual tweaks, and new components are delivered to the stable channel automatically.
Major releases are not applied automatically. They take effect only once you change the major number in the URL — so your team controls the timing.
Existing apps are explicitly stated to need no immediate action. Still, it is worth taking stock early of which URL you are actually using.
Security fixes are applied to the affected stable releases, andolder majors are included as well. In other words, you are not forced to move up a major version just to receive security fixes.
@shopify/polaris-types keeps its major version in syncThe types package uses thesame major versionas the CDN release. If you bump the major on the CDN side, plan on bumping the types package major to match.
Apps should use the stable release channelby default. Updates to stable arrive only after passing through the release candidate (RC) phase. This URLdoes not move up automatically across major versions.
When it comes to regular feature additions, fixes, and visual changes, a pinned release simply doesnot receive them.
polaris-1.1.js is published only once Polaris 1.1 reaches stable. You cannot point a pinned URL at a version that has not reached stable yet.All upcoming changes can, before they are released to the stable channel,be tested in release candidate builds. RC versions accumulate improvements during the RC period and areupdated in place at the same URL. Intended for development and testing use.
polaris.js URLexisting polaris.js and polaris-1.js areupdated at the same time. Andthey don't move up automatically even when a major release ships.
polaris-2.js in the diagram is notation used to show the structure "moving up a major = rewriting the major version number in the URL."The article states no plans or release timing for Polaris 2.| URL | Compatible updates (minor / fix) | Automatic major upgrades | Primary use |
|---|---|---|---|
polaris-1.jsstable · default |
Receives Arrives after the RC phase | Not applied | The baseline. Apps should use the stable channel by default |
polaris.jsExisting URL |
Receives polaris-1.js — updated at the same timing |
Not applied | Existing apps can stay as they are (no immediate action needed) |
polaris-1.1.jsPinning |
Not received No regular features, fixes, or visual changes | No | Controlling production rollout timing / reproducing tests / recovery / release synchronization |
polaris-1.1-rc.jsRelease candidate |
Updated in place during the RC period | — | For development and testing. Check upcoming changes ahead of time |
* Note: for pinned URLs (polaris-1.1.js), the article doesn't explicitly say whether security fixes are applied. All it states is that security fixes go to affected stable releases, which may include older majors.
Loading Polaris Web Components from the Shopify CDN —third-party apps
@shopify/polaris-types — developers using it
App Home UI extensions
Admin UI extensions
App Bridge
Backward-compatible improvements arrive silently, but breaking changes will never reach you unless you rewrite the URL.There's exactly one control point: the major version number in the URL. Put that under configuration management and you're covered.
RC builds keep being updated in place at the same URL.It isn't reproducible, so never use it in production. Treat it as strictly for development and test environments.
You stop receiving all regular features, fixes, and visual changes.It's a temporary measure for timing control, reproduction, and recovery — not a permanent setup, so always pair it with a plan to unpin.
@shopify/polaris-types uses the same major version as the CDN release.If the major in your script tag and the major in package.json drift apart, your types and the actual runtime won't match. Checking that the two match in CI is cheap insurance.
Security fixes are applied to the affected stable releases,including older majors. So there is little need to rush a major upgrade for security reasons. That said, features and improvements only land on the newer major, sochoosing not to upgrade accumulates as a cost on the feature side. Note that the support period and EOL policy for older majors arenot stated in the article.
cdn.shopify.com/shopifycloud/polaris across every repository, then catalog the results into four buckets: stable / RC /polaris.js / polaris-1.js / -rc.js / pinned. Move only the ones hitting an RC in production to stable right away.polaris-1.1-rc.js , and leave production on polaris-1.js . Run visual regression tests on your main screens on a schedule throughout the RC period.polaris-1.1.js) ③ If it recovers, the cause is confirmed as Polaris → return to stable after a permanent fix."