Polaris, Shopify’s official design system, just hit a major milestone. The 2.0 release is now marked as stable on the Polaris CDN, meaning the new visual language that mirrors the redesigned admin is ready for production use. This post breaks down exactly what changed, who the update affects, and the concrete steps you need to take to keep your apps and extensions running smoothly.
What is Polaris 2.0?
Polaris 2.0 is the next‑generation UI library that powers the Shopify admin experience. It introduces a refreshed frame, revamped navigation, and a modern visual palette while keeping the same component API surface that developers rely on. The biggest difference is that it follows a semantic versioning model on the CDN, allowing you to lock into a specific 2.x release or automatically receive future minor updates.
Stable CDN URLs and Semantic Versioning
The stable CDN now hosts two entry points: https://cdn.shopify.com/shopifycloud/polaris-2.js and https://cdn.shopify.com/shopifycloud/polaris-2.0.js. The first URL always points to the latest 2.x version, whereas the second URL is pinned to the exact 2.0 release. Importantly, the original polaris.js and polaris-1.js continue to serve the 1.1 series and will never be upgraded to 2.x, so you must change your script tag to start using the new version.
Immediate impact for developers
If your app still loads <script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script> you are still on Polaris 1.1. Nothing will break, but you’ll miss out on the new admin look, performance improvements, and upcoming component enhancements. Switching to the new script is a single‑line change, but it also opens the door to new TypeScript definitions and a tighter integration with Shopify’s React Router template.
To upgrade, replace your existing tag with: <script src="https://cdn.shopify.com/shopifycloud/polaris-2.js"></script> or, if you prefer to stay on the exact 2.0 release, use <script src="https://cdn.shopify.com/shopifycloud/polaris-2.0.js"></script>.
Updating React Router‑based apps
Apps built from the official React Router starter require an additional configuration step. Both the AppProvider on the client side and the shopifyApp server configuration expose a polarisUrl property that must point to the same script. After updating the CDN tag, set the URL in your code as shown below.
javascript
import {AppProvider} from '@shopify/polaris';
const polarisUrl = 'https://cdn.shopify.com/shopifycloud/polaris-2.js';
<AppProvider
i18n={translations}
apiKey={process.env.SHOPIFY_API_KEY}
shopOrigin={shopOrigin}
polarisUrl={polarisUrl}
>
{/* Your app */}
</AppProvider>
And server config (e.g., using @shopify/shopify-app-express):
javascript
app.use(
shopifyApp({
apiKey: process.env.SHOPIFY_API_KEY,
secret: process.env.SHOPIFY_API_SECRET,
scopes: ['read_products', 'write_orders'],
polarisUrl: 'https://cdn.shopify.com/shopifycloud/polaris-2.js',
// other options…
})
);
Also note you need @shopify/shopify-app-react-router version 2.1.0 or newer for the polarisUrl prop to be recognized.
TypeScript support and new typings
Polaris 2.0 ships with an updated set of TypeScript definitions. Install the new types package with npm i @shopify/polaris-types@^2.0.0 or yarn add @shopify/polaris-types@^2.0.0. The typings reflect the new component props and the revised color palette, giving you compile‑time safety as you migrate.
What merchants should know
Merchants don’t need to take any direct action; the UI change is purely on the app side. However, if a merchant installs an app that still uses Polaris 1, the app’s admin screens will look out‑of‑sync with the rest of the Shopify dashboard. Encouraging app developers to upgrade ensures a consistent experience for store owners.
Action checklist
1️⃣ Replace the old script tag with polaris-2.js (or polaris-2.0.js to lock the version). 2️⃣ If you use the React Router starter, add the identical polarisUrl to both the client AppProvider and the server shopifyApp config. 3️⃣ Update the @shopify/shopify-app-react-router package to ≥ 2.1.0. 4️⃣ Install the new TypeScript types (@shopify/polaris-types). 5️⃣ Test your UI in a development store to verify component styling and navigation behave as expected.
Conclusion
Polaris 2.0 is now the default UI foundation for Shopify apps. Making the switch today not only aligns your app with the latest admin design but also positions you to receive future 2.x improvements without extra work. Need help migrating? Reach out to our Shopify Partner community or drop a comment below—let’s get your app looking its best.
