Polaris Web Components loaded from the Shopify CDN are moving to semantic versioning. Most apps will continue receiving compatible improvements automatically, while developers can choose when to adopt breaking changes. Existing apps don’t need to take immediate action.
What changed
Polaris CDN releases now follow familiar semantic versioning rules:
-
Major releases may contain breaking API or behavioral changes that require app updates.
-
Minor releases contain compatible components, APIs, bug fixes, accessibility and performance improvements, and visual refinements.
-
Security fixes can be applied to affected stable releases, including older majors.
The @shopify/polaris-types package uses the same major version as the CDN release.
Releases
Automatic compatible updates
Apps should by default use the stable release channels, you will receive updates to this channel after updates have gone through a release candidate phase. This URL will not automatically get updated if there is a major change. Adopting a new major is always explicit.
Pinned releases
A pinned release doesn’t receive normal features, fixes, or visual changes.
Pinning is useful when you need to:
-
Control when normal changes reach production.
-
Reproduce the release used during testing.
-
Recover from an update affecting your app.
-
Coordinate Polaris updates with your release process.
Note: polaris-1.1.js is published only when Polaris 1.1 becomes stable.
Testing upcoming changes
All upcoming changes will be available to test in release candidate builds prior to being released in stable channels.
This release candidate version will accumulate improvements during the release candidate window and update in-place at the same URL. It’s intended for development and testing.
Existing polaris.js URL
The existing polaris.js will be updated at the same time as polaris-1.js and will not automatically update when there is a major release.
Who’s affected
This applies to third-party apps that load Polaris Web Components from the Shopify CDN and developers using @shopify/polaris-types.
It doesn’t change versioning for App Home UI extensions, Admin UI extensions or App Bridge.
FAQ
Which URL should I use?
polaris-1.js. You get compatible improvements automatically and never cross a major boundary without deciding to.
Will my app automatically move to Polaris 2?
No. Major adoption is always an explicit change to your script tag. That is true of polaris-1.js and of the polaris.js URL.
What happens to polaris.js?
It will follow the same updates as polaris-1.js automatically getting improvements and will not cross a major boundary.
Can I use a release candidate in production?
You can, but it is subject to changes during the release candidate window. RC URLs change in place as the release accumulates.
Do older majors still get fixes?
Normal bugs fix forward into the current release rather than being backported.
How long will the 1.1 release candidate be available?
Long enough to give you time to test your app and send us feedback. We’ll announce the stable release in the changelog and in this topic.
Is App Bridge versioned?
No. App Bridge stays unversioned at app-bridge.js.