November 5, 2026 · 8 min read

Migrating an Embedded Shopify App to Polaris Web Components After Polaris 2.0

Polaris 2.0 is stable and Polaris React is deprecated. Here is the complete mechanical guide to migrating an embedded Shopify app to Polaris web

Migrating an Embedded Shopify App to Polaris Web Components After Polaris 2.0

Polaris 2.0 went stable on the Shopify CDN on October 22, 2026, and the @shopify/polaris React package is now formally deprecated and archived. If your embedded app still renders <Page> and <DataTable> from @shopify/polaris, you are running a library that receives no further updates, security patches, or new components. The migration path is well-defined: strip the npm dependency, inject a CDN script tag, replace React JSX component trees with s-* custom elements, and wire events through the DOM instead of callback props.

Key takeaways

  • polaris.js and polaris-1.js both stay on Polaris 1.x forever and will never serve 2.x. You must explicitly change your script tag to polaris-2.js.
  • All API versions 2025-10 and later use Polaris web components by default. Extensions on 2025-07 or earlier were blocked from updates after October 1, 2026.
  • React 18 cannot drive controlled s-* form fields. You must upgrade to React 19 before migrating any controlled inputs.
  • Polaris React and Polaris web components can coexist in the same app during migration, so you can ship in slices.
  • Built for Shopify apps must match the new admin visual style by May 1, 2027.

Why the CDN model exists

The old @shopify/polaris npm package bundled React, reconciler, and design tokens into every app build. That approach worked when React was the only relevant renderer, but Shopify now ships UI across App Home, checkout extensions, POS extensions, and customer account pages, all with different sandbox constraints.

Remote-dom, Shopify's library for cross-platform UIs, mirrors real DOM nodes from an isolated sandbox to the host, so any DOM-rendering framework works. Polaris web components are framework-agnostic custom elements that sit on top of that. Shopify proved the approach internally when it migrated five high-traffic Checkout Blocks extensions from React to Preact with Polaris web components, cutting bundle sizes between 40 and 85 percent. The largest single extension shrank 84.4 percent. The 2026-01 remote-dom CLI enforces a hard 64 KB gzip ceiling per extension, down from bundles that were previously 100 to 112 KB gzipped.

For an App Home embedded app the story is simpler: Polaris loads from cdn.shopify.com/shopifycloud/polaris-2.js as a single script tag, registers custom elements in the browser, and components update with every compatible minor CDN release without a redeploy.

The CDN versioning model (understand this first)

Shopify announced semantic versioning for the Polaris CDN on August 31, 2026. The rules matter before you touch a single file.

CDN URLWhat it servesWhen to use
polaris.js (legacy)Polaris 1.x, frozen at 1.1Never for new work. Never moves to 2.x.
polaris-1.jsLatest stable 1.xStaying on 1.x intentionally
polaris-2.jsLatest stable 2.xRecommended production target
polaris-2.0.jsPinned exactly to 2.0.0When you want to control the exact release
polaris-2.0-rc.js2.0 release candidateTesting against the RC; not for production

The @shopify/polaris-types npm package mirrors the CDN major version. If you load polaris-2.js but your tsconfig resolves @shopify/polaris-types@^1, TypeScript compiles against the wrong component API and you will miss property renames silently. Install @shopify/polaris-types@^2.0.0 before any other step.

Two separate migration tracks

The phrase "migrating to Polaris web components" actually covers two different situations that require different work:

Track A: Already on Polaris web components (Polaris 1.x), adopting Polaris 2.0

Your app renders s-* tags but loads polaris.js or polaris-1.js. Adoption is a two-file change: update the CDN script tag to polaris-2.js and bump @shopify/polaris-types to ^2.0.0. Then test. The visual changes are real, particularly s-frame, s-nav-menu, and s-button, which pick up the redesigned admin's new color and spacing tokens when the merchant's store has received the new admin design.

Track B: Still on Polaris React (@shopify/polaris), migrating to web components

This is the larger project. The rest of this post is primarily about Track B.

Step 0: Audit before you write a line

Before touching any code, map the blast radius:

  • Run grep -r "@shopify/polaris" src/ --include='.tsx' --include='.ts' -l to find every file with a Polaris React import.
  • Identify packages in node_modules that re-export @shopify/polaris components internally. Those are silent blockers because their own JSX will not migrate automatically.
  • Check for any CSS that overrides .Polaris-* class names. Shadow DOM in web components makes those overrides unreachable, so they will silently stop working.
  • Record your current React version. If you are on React 18, you must upgrade to React 19 before you migrate any controlled form fields. React 18 lacks the custom-element property and event behavior that controlled Polaris web components rely on.

Step 1: Set up dual rendering

Polaris React and Polaris web components can render in the same app while you migrate. That is intentional and supported. You do not need a big-bang rewrite.

Add the CDN script tag and types now, before touching components:

<!-- app/root.tsx or your top-level layout -->
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js"></script>

Note the load order: the Polaris script must come after App Bridge. If you inject it before App Bridge registers the shopify global, some App Bridge component integrations will fail silently.

For React Router template apps, polarisUrl must be set in two places:

// app/shopify.server.ts
const shopify = shopifyApp({
  // ...
  polarisUrl: "https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js",
});
// app/routes/app.tsx
<AppProvider
  isEmbeddedApp
  polarisUrl="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js"
>
  <Outlet />
</AppProvider>

Mismatching these two locations causes the CDN script to load twice or not at all, which is a common failure mode. Check the Network tab and confirm exactly one request to the Polaris CDN before proceeding.

Step 2: Migrate in route slices

Shopify's official guidance is to migrate the app in working slices rather than all at once. A web-component leaf can render inside a Polaris React page during migration. What to avoid is migrating layout chrome (the equivalent of Frame, TopBar, or Navigation) independently of the pages inside it, because inconsistent spacing tokens between the two systems create visual gaps that are annoying to debug.

A practical order for most apps:

  1. Non-interactive display components first: <Badge>, <Banner>, <Icon>, <Text>. These have no event wiring and are low risk.
  2. Action components: <Button>, <Link>. Events change from React onClick props to native DOM event listeners.
  3. Layout components: s-page, s-section, s-layout. Migrate an entire route's layout in one commit so spacing is consistent.
  4. Controlled form fields last: s-text-field, s-select, s-checkbox. These require React 19 and event rewiring.
  5. App shell last: Frame, AppProvider, Navigation. Remove these only after every other Polaris React consumer is gone.

Event wiring change

This is the single biggest source of bugs during migration. Polaris React used React synthetic callback props:

// Before: Polaris React
<TextField value={val} onChange={(newVal) => setVal(newVal)} />

Polaris web components communicate state through standard DOM events:

// After: Polaris web component in a React 19 JSX tree
<s-text-field
  value={val}
  onInput={(e: Event) => setVal((e.currentTarget as HTMLInputElement).value)}
/>

Note e.currentTarget.value, not e.target.value. Polaris web components lean on the element reference itself, not a bubbling target. Getting this wrong produces fields that read the initial value correctly but never update on user input.

Component mapping: what changes and what is missing

Polaris ReactPolaris Web ComponentNotes
<Page><s-page>Title bar handed to admin chrome via App Bridge
<Card>No s-card existsUse <s-section> or the card pattern from the compositions library
<DataTable><s-data-table>Available; IndexTable has no direct equivalent yet
<Autocomplete>No equivalent yetLeave on Polaris React; both libraries can coexist
<Banner><s-banner>Available
<Badge><s-badge>Available
<Frame>RemovedAdmin chrome is owned by App Bridge
<Navigation><s-app-nav> (App Bridge)Lives outside the iframe in admin chrome
<AppProvider>Remove after last Polaris React consumerNo web-component equivalent needed

The gap that catches teams most often is IndexTable. It existed in Polaris React and has no direct s-* equivalent at the time of writing. The recommended workaround is to leave those specific screens on Polaris React while migrating everything else. Shopify explicitly supports this hybrid state.

textAlign was also removed from s-paragraph and s-heading during the web components redesign, which breaks centered-text layouts. Use CSS grid or flexbox on a wrapper element instead.

Step 3: Remove the shell and test

Once every route is on web components, remove AppProvider, Frame, and all Polaris React stylesheets. Then:

  • Run TypeScript strict mode and confirm zero residual @shopify/polaris import paths.
  • Verify keyboard navigation: s-* components implement ARIA roles natively, but check tab order across modals and form flows.
  • Test at multiple viewport sizes. s-page behaves differently from the old Page at narrow widths.
  • Use the browser DevTools Shadow DOM inspector to confirm that styles are coming from within the component, not from your own overrides that now have no effect.

Shopify also provides an AI Toolkit that handles the mechanical parts of React-to-Preact conversion and component mapping for UI extensions, pointed at the official docs via the Shopify Dev MCP server.

Step 4: Adopt Polaris 2.0

Once your app is fully on Polaris web components (Track A or the end of Track B), switching to Polaris 2.0 is a script tag update:

<!-- Switch from polaris-2.0-rc.js or polaris-1.js to: -->
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.js"></script>

And in package.json:

npm install @shopify/polaris-types@^2.0.0

For React Router template apps, bump @shopify/shopify-app-react-router to ^4.0.0, which loads polaris-2.js by default and sets @shopify/polaris-types@^2.0.0 in its peer dependencies.

Test against a development store with the new admin design feature preview enabled. Components render the new visual style (new color, typography, spacing, and icons) in stores that have received the redesign, and fall back to the Polaris 1.1 appearance in stores that have not. If you render outside the admin entirely, components default to the new visual style.

A note on UI extensions vs App Home

This post focuses on App Home embedded apps. UI extensions (checkout, customer account, POS) have a separate migration path: they move to remote-dom with Preact rather than React, and the bundle budget is hard at 64 KB gzip. Extensions automatically receive the Shopify admin design without loading the CDN bundle themselves. If you have both App Home pages and UI extensions, treat them as separate migration projects with separate timelines. The deadline pressure is heavier on extensions: apps with extensions on API versions 2025-07 or earlier were already blocked from CLI updates as of October 1, 2026.

Verification checklist

  • [ ] Network tab shows exactly one Polaris CDN request, loading after App Bridge
  • [ ] @shopify/polaris-types version matches CDN major (^2.0.0 for polaris-2.js)
  • [ ] polarisUrl is set in both AppProvider and shopifyApp() for React Router apps
  • [ ] React 19 is running before any controlled s-* form field is in the tree
  • [ ] No @shopify/polaris import remains in production routes (grep to confirm)
  • [ ] No .Polaris-* CSS overrides remain (they are unreachable through Shadow DOM)
  • [ ] TypeScript strict mode passes with zero implicit any on s-* element refs
  • [ ] Keyboard navigation tested through all modal and form flows
  • [ ] Development store with new admin design feature preview enabled has been used for final sign-off

Teams without in-house Shopify developers can bring this to Lintel, my Shopify engineering studio, for custom Shopify app development.

shopifypolarisweb-componentsembedded-appsapp-bridge

Frequently asked questions

Do I need to migrate to Polaris web components if my embedded app still works?

Polaris React is deprecated and no longer receives updates, security patches, or new components. It will continue to run for now, but Built for Shopify apps must adopt the new visual style by May 1, 2027, and you cannot receive new components or bug fixes on the deprecated library. Starting the migration now gives you time to do it incrementally without a deadline forcing a rushed rewrite.

Can I use Polaris web components with frameworks other than React?

Yes. Polaris web components are built on the Web Components standard and are framework-agnostic custom elements. You can use them with React 19, Preact, Vue, plain JavaScript, or no framework at all. The only React-specific requirement is React 19 or later if you need controlled form fields driven by React state.

What is the difference between polaris.js, polaris-1.js, and polaris-2.js on the CDN?

polaris.js is the old unversioned URL that tracks Polaris 1.x and will never serve 2.x. polaris-1.js serves the latest stable 1.x release. polaris-2.js serves the latest stable 2.x release and is the recommended production target after migrating to web components. You must explicitly change your script tag to adopt a new major version.

Seven years of Shopify, on one page.

Roles, projects, stack and certifications are on the resume.

Resume Download PDF LinkedIn