Shopify Polaris 2.0 for App Home: Upgrade Checklist

Shopify Polaris 2.0 is the next version of the web components that style your app’s pages inside the Shopify admin, and it is currently a release candidate. If your app home uses only Polaris web components, the upgrade is mostly a script change. If it still renders React Polaris components, it will keep the old look until you migrate. This checklist covers the CDN change, the audit points Shopify lists and how to test the new admin design. Checked against Shopify’s Polaris 2 upgrade guide and the Polaris 2.0.0-rc.1 changelog.

What Polaris 2 Changes

Shopify is updating the admin’s frame, navigation and visual appearance, and Polaris 2.0 updates the web components to match. The styling is chosen at runtime. App Bridge signals the admin’s style, and Polaris web components match it when they initialize, so your app needs no API calls or configuration for this.

• Web components only: if your UI uses only Polaris web components, you only need to load Polaris 2.0. No code changes are required.
• Still on React Polaris: apps that render @shopify/polaris React components keep the current look until you migrate them to web components.
• Polaris 1: it does not include the updated styling, so apps on it keep today’s appearance.

Switch to the Polaris 2.0 Script

The release candidate is served from https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js. The unversioned polaris.js never serves 2.x, so it stays on Polaris 1.

• React Router template: set polarisUrl on AppProvider in app/routes/app.tsx and in shopifyApp in app/shopify.server.ts, with the same value in both. This needs @shopify/shopify-app-react-router 2.1.0 or later. Do not add a separate Polaris script tag, because that loads a second bundle and causes a failure.
• Your own script tag: change the Polaris src to the 2.0 RC URL and load it after app-bridge.js. App Bridge must come first so it can publish the admin’s style signal.
• TypeScript: match @shopify/polaris-types to the loaded release. For the RC use ^2.0.0-rc.0, because a ^2.0 range resolves to nothing while 2.0 is a prerelease.

Audit Checklist: What Can Break

• Duplicate bundles. Two Polaris scripts cause an error. Check for stale tags from bundler aliases or shared layouts.
• Mixed React and web components. React Polaris components keep the old look and will not match restyled web components next to them.
• Custom CSS. Styles that read Polaris custom properties or hardcode @shopify/polaris-tokens values stay on the old palette.
• Fonts. The updated admin uses ShopifyInter. Hardcoded Inter or custom stacks keep the old type, and font loading that exists only for Polaris can be removed.
• Hand-built lookalikes. Custom cards, badges, banners and empty states matched by eye will look off beside restyled components.
• Fixed-bottom elements. Position them with var(--shopify-safe-area-inset-bottom, 0px) so they clear the admin overlay, such as the Sidekick bar.

What Is New in 2.0.0-rc.1

The first release candidate was published on October 1, 2026. It lists no added or removed components and no breaking changes. The changelog groups the work into three areas.

• Components: Table matches the updated admin design, Tooltip can sit in Section’s supplemental slot, Section supports equal-height cards in a Grid, Select matches the height of TextField, Badge uses a pill shape on mobile and Banner title contrast is improved.
• Layout fixes: on narrow screens a Section’s primary action moves below the card, and several spacing and menu icon details were corrected.
• Reliability and speed: globalThis.polaris state is no longer lost when a page loads the bundle more than once, Modal actions fire a bubbling click even with commandFor set, and mounting and updates are faster, especially on pages without React.

How to Test the New Design

Shopify suggests testing on a development store with the new admin design feature preview, created with shopify store create dev and the --feature-preview new_admin_design flag. Test again on any dev store without the preview to confirm the current look still works, since merchants will see both for a while.

Our Analysis: Test Now, Switch to Stable Later

Treat the RC as a soak test. Shopify says changes can still happen during the soak period and may affect your app, and it gives no release date. Our advice is to test on a dev store now and keep the production script on Polaris 1 until the RC is promoted.

Remove duplicate sources of truth. The most likely failure is two Polaris bundles loaded by different layers. Search your app for every place a Polaris script, import or alias is added before you change the URL.

Use this as a reason to finish the web component move. Mixed pages are the ones that will look inconsistent. If you also build checkout or customer account extensions, our guide to migrating UI extensions to web components covers the same direction on the extension side, and the Sidekick app extensions guide explains why the bottom overlay matters.

FAQ about Polaris 2

Is Polaris 2.0 stable? Not yet. Shopify describes the app home version as a release candidate with no stated release date.

Do I need code changes? Not if your app uses only Polaris web components. You load Polaris 2.0 and the styling follows the admin.

Why not use the unversioned script? It never serves 2.x. Switching to 2.0 means pointing at the 2.0 URL or setting polarisUrl in the React Router template.

Can I load both versions? No. Loading two Polaris scripts causes an error.