Independent analysis of Shopify's public developer documentation. Identity Forge is not affiliated with or endorsed by Shopify. Shopify and Polaris are trademarks of their owner. Migration status and package details reflect the documentation at time of writing — verify against shopify.dev before planning a migration.
The deprecation, stated plainly
The Polaris React documentation site now carries a deprecation label in its own heading, alongside a banner pointing to Polaris Web Components. If you are searching for Polaris and landing on React component docs, you are reading the previous generation.
The React library is not gone — the foundations, components, tokens and icon documentation are still published — but the direction is unambiguous. New Shopify apps get web components, and Shopify CLI wires them in during scaffolding.
How Polaris Web Components are delivered
This is the part that differs most from what design system users are used to, and it is a single script tag:
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>
</head>That is the whole installation. In a Remix app it is the same tag placed in the root document:
// app/root.tsx
export default function App() {
return (
<html>
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/polaris.js" />
</head>
</html>
)
}TypeScript users add a companion package, @shopify/polaris-types, from npm. Shopify's documentation is specific about how to keep them aligned: because the CDN always serves the latest components, you should specify @shopify/polaris-types@latest in package.json so the types track them.
Read that last sentence twice if you have opinions about lockfiles. The runtime components are not versioned by you — the CDN serves the current release — and the recommended way to keep types correct is to depend on @latest. That is a deliberate inversion of normal dependency hygiene, and whether it is acceptable depends entirely on the deployment context.
Why the vendor wants to own the version
The stated purpose of Polaris in the app context is that your app should look and feel native to the Shopify admin. That is a genuinely different requirement from "your app should be consistent", and it explains the delivery model completely.
If the Shopify admin's visual language changes — a spacing revision, a new type scale, a dark mode — an app pinned to a component version from eighteen months ago now looks wrong inside it. Not broken. Wrong, in the specific way that reads to a merchant as a low-quality app. Multiply that by an app marketplace and the platform's own surface becomes visibly inconsistent through no fault of any individual developer.
Serving components from a CDN moves that risk from thousands of app developers, who have no incentive to upgrade a working dependency, to one platform team that does. It is the same instinct behind Stripe's app UI toolkit refusing arbitrary CSS: when your UI renders on someone else's surface, they take the styling decisions back.
| npm package | CDN script | |
|---|---|---|
| Who controls the version | You, via the lockfile | The vendor |
| Breaking change | Arrives when you choose. May never arrive | Arrives when the vendor ships it |
| Platform consistency | Degrades over time as apps fall behind | Maintained automatically |
| Offline / air-gapped | Works | Does not |
| Bundle size | Yours to optimise, tree-shakeable | Not in your bundle at all; a separate request |
| Right when | Your app is the surface | Someone else's app is the surface |
The bottom row is the whole decision. This is not a general recommendation to serve your design system from a CDN — for a product where you own the surface, giving up version control buys you nothing and costs you reproducible builds. It is the correct answer to a specific structural question about who is accountable for how the page looks.
Why web components rather than React
The CDN model explains itself once you accept the platform-consistency goal, but it also more or less forces the technology choice. You cannot ship React components from a script tag into an app that might be built with Remix, plain HTML, Vue, or something that did not exist when the decision was made. Custom elements are the only widely supported format that renders identically regardless of what wraps them.
Shopify's documentation notes you can add the script tag in any framework. That sentence is doing a lot of work: it is the entire reason for the migration expressed as a capability.
It is worth naming the cost, because web components are not free. You give up React's ergonomics — typed props checked at build rather than runtime, familiar composition patterns, the ecosystem of React-specific tooling — in exchange for framework independence. The @shopify/polaris-types package exists precisely to claw back the first of those. Whether the trade is good depends on whether framework independence is worth anything to you, and for a platform serving an app marketplace it is worth a great deal.
What Polaris is besides components
The component-library churn obscures the fact that most of Polaris's transferable value is not components at all. The documentation site publishes four things, and three of them survive any implementation change:
| What it is | Useful outside Shopify? | |
|---|---|---|
| Foundations | Design guidance for building quality admin experiences | Yes. Admin UX guidance is admin UX guidance |
| Tokens | Coded names representing design decisions — colour, spacing, typography | As a model, yes. As values, only if you want to look like Shopify |
| Icons | Over 400 icons focused on commerce and entrepreneurship | Yes, if you build commerce software. Check the licence |
| Components | The implementation, now web components | No. They are built for the Shopify admin specifically |
The icon set is the underrated one. Four hundred icons drawn for commerce — fulfilment states, discounts, inventory, shipping, payment concepts — is a large amount of specialised drawing work, and generic icon sets are noticeably bad at exactly these concepts. If you build anything in commerce, this is worth an hour of your time and a look at the licence terms.
The tokens are worth studying as a naming exercise even if the values are useless to you. Shopify's description — coded names that represent design decisions — is the correct definition, and it is the one most teams fail to implement when they name a token blue-500 instead of naming the role it plays.
The pattern across three systems
Polaris is one of three large enterprise design systems that made a structural change in roughly the same window, each betting differently on the same premise: that the code consuming a design system is increasingly not written by a human reading the docs.
| What changed | The underlying bet | |
|---|---|---|
| Shopify Polaris | React deprecated; framework-agnostic web components from a CDN | The delivery format must not assume what generated the page |
| IBM Carbon | An MCP server exposing docs and code examples to agents | Agents should retrieve the system rather than recall it |
| Salesforce Lightning (SLDS 2) | CSS architecture decoupled from visual style; a linter validating markup against the rules | The system must be themeable enough for generated UI, and violations must be caught mechanically |
Polaris's version is the least discussed and arguably the most consequential for anyone building on a platform. If an AI agent scaffolds a Shopify app, it does not need to know which framework the developer chose, because the components are the same custom elements either way. Framework-agnostic delivery is agent-agnostic delivery, whether or not that was the motivation.
What this does not solve
A component library — CDN-delivered, framework-agnostic, always current — tells an agent what components exist and how to call them. It says nothing about what your product should look like, because in the Shopify app case the answer is fixed: it should look like the Shopify admin.
Outside that case, the question is open and nothing in a component library answers it. We sampled 299 DESIGN.md files written to give agents that answer. 86% listed colours as raw hex with no role attached, 76% stated no prohibitions, 57% defined no motifs, and 54% relied on a vague adjective — "clean" in 39%, "modern" in 36%. A model reading that file has a palette and no design.
Identity Forge design kits answer the other half: semantic colour roles across light and dark, type and spacing scales, motifs, and explicit do's and don'ts, serialised into a DESIGN.md that works alongside any component library. Browse the kits, or start with what a DESIGN.md file is.
Practical guidance
- Building a Shopify app now? Use Polaris Web Components. Scaffold with Shopify CLI and it is wired in; add
@shopify/polaris-types@latestif you are on TypeScript. - Maintaining a Polaris React app? It still works, but you are on a deprecated implementation. Read the current migration guidance before planning anything else large in that codebase.
- Building something outside Shopify? Do not adopt Polaris components. Do look at the foundations and the commerce icon set, and treat the token naming as a worked example.
- Maintaining your own design system? The transferable question is not React versus web components. It is whether you or your consumers should control the version — and that follows from who is accountable for how the result looks.
Is Polaris React deprecated?
Yes. The Polaris React documentation site carries a deprecation label and points to Polaris Web Components. Existing React apps continue to work, but new Shopify app development uses the web components, which Shopify CLI adds automatically when scaffolding.
How do I install Polaris Web Components?
You do not install them from npm. Add a script tag pointing at https://cdn.shopify.com/shopifycloud/polaris.js in your document head, along with the shopify-api-key meta tag. Shopify CLI does this for you when you scaffold an app. TypeScript users add @shopify/polaris-types from npm for types.
Why does Shopify serve components from a CDN instead of npm?
So apps stay visually native to the Shopify admin as it changes. A pinned npm dependency means an app frozen at an old visual language inside a surface that has moved on, which reads to merchants as a low-quality app. Moving version control to the platform fixes that for the whole marketplace at once.
Can I use Polaris outside a Shopify app?
The components are built for the Shopify admin and are the wrong choice elsewhere — they will make your product look like Shopify. The foundations documentation, the token naming approach and the 400+ commerce-focused icons are genuinely useful outside Shopify; check the licence terms before shipping the icons.
What are Polaris tokens?
Coded names representing design decisions for colour, spacing, typography and more. The naming approach is the transferable part: a token should be named for the decision it encodes rather than the value it holds, which is the difference between a token system and a list of variables.