Executive summary
- Polaris Web Components served from the Shopify CDN now follow semantic versioning, with distinct stable, pinned, and release candidate URLs.
- Breaking changes become opt in, so a new major version can no longer reach your embedded admin app without a deliberate edit on your side.
- This concerns any team maintaining custom, private, or partner-built Shopify apps. Existing apps require no immediate action.
What changed
Shopify has put a version contract around the Polaris Web Components bundle it serves from its CDN. Three channels now exist. The stable channel, loaded as polaris-1.js, continues to deliver compatible improvements and fixes automatically, but it will never move you to a new major on its own. A pinned channel, such as polaris-1.1.js, freezes on an exact minor and stops receiving normal feature, fix, or visual changes. A release candidate channel, polaris-1.1-rc.js, accumulates upcoming changes in place while a minor is being finalised and is intended for development and testing only.
The categories follow the usual rules. Minor releases carry new components, compatible API additions, bug fixes, and accessibility and visual refinements. Major releases are where breaking API and behavioural changes live, and adopting one is always an explicit change to your script tag. Security fixes can still be applied to affected stable releases, including older majors. The @shopify/polaris-types package tracks the same major as the CDN build you load. The legacy polaris.js URL updates alongside polaris-1.js and will not jump majors on its own. App Home UI extensions, Admin UI extensions, and App Bridge keep their existing versioning and are unaffected.
Why it matters
A great deal of enterprise operational logic lives in custom admin apps: order triage, ERP exception queues, bulk merchandising tools, warehouse dashboards. Until now the front end of those tools sat on a moving dependency loaded straight from a CDN, outside your build and outside your test suite. A visual or behavioural change could reach production without a deploy on your side, and the first signal was often a support ticket from a merchandiser.
Semantic versioning converts that unbounded risk into a scheduled one. You decide when to absorb a major, you can freeze a version through peak trading, and you can reproduce the exact bundle a QA cycle ran against. For any business running a code freeze from November through December, the pinned channel is the immediate practical win.
Role-specific impact
- Marketers: little direct change. The admin tools your team uses for campaign setup and bulk edits should become steadier, with fewer unexplained interface shifts mid-campaign.
- Developers: choose a channel per app and write the decision down. Stable for routine tooling, pinned where reproducibility matters, release candidate in development only. Keep the types package aligned to the same major.
- Store admins: expect fewer surprise interface changes inside custom apps, and expect the changes that do arrive to land on a schedule your development team controls.
Use-case example
Real-world scenario
A Plus merchant operating four regional stores runs a custom app that reconciles ERP inventory exceptions, used daily by roughly 30 warehouse staff. Last year an upstream component change altered modal dismissal behaviour, and staff lost partially entered reconciliations for two days before anyone traced the cause. Moving that app to a pinned Polaris URL for the October through January freeze window, then adopting the next minor in a February release with half a day of regression testing, removes that class of incident from the peak period entirely. The cost is one line in a script tag and a calendar entry.
Implementation checklist
- Inventory every custom, private, and partner-built app that loads Polaris Web Components from the Shopify CDN.
- Record the URL each one currently uses, including any legacy polaris.js references.
- Choose a channel per app: stable for routine tooling, pinned for anything relied on during a code freeze.
- Align @shopify/polaris-types to the same major version as the CDN bundle you load.
- Point staging, and only staging, at the release candidate URL, and schedule a smoke test before each minor goes stable.
- Name the owner of the decision to adopt the next major, and put a review date on the roadmap.
FAQ
Q: Do we need to change anything right now?
A: No. Existing apps keep working and the stable channel behaves as it did. The value is in choosing a channel deliberately rather than inheriting one by default.
Q: Does this change App Bridge or our Admin UI extensions?
A: No. The change covers Polaris Web Components loaded from the CDN and the matching types package. App Home UI extensions, Admin UI extensions, and App Bridge keep their existing versioning.
Resources
App Home documentation on shopify.dev
Need guidance? Talk to Makro.