Polaris 2.0 Migration for Shopify Embedded Apps

Polaris 2.0 is now stable, and if you maintain a Shopify embedded app, you need a migration plan. This guide covers what changed, what breaks, and how to move your admin UI to Polaris 2.0 without downtime.

Polaris 2.0 is not a drop-in update. It changes component APIs, design tokens, and layout primitives. Apps built on Polaris 1.x will see visual and functional differences. The good news: you can migrate incrementally, test thoroughly, and roll back if needed. Below is a practical path.

What Polaris 2.0 changes in practice

Polaris 2.0 is a major release. It removes deprecated patterns, renames props, and introduces new layout components. Here are the key changes:

Components and props

• Button: primary and destructive props are replaced by variant. Use variant="primary" instead of primary.
• Card: sectioned is deprecated; use padding or wrap content in BlockStack.
• Stack: replaced by InlineStack and BlockStack for horizontal and vertical layouts.
• TextStyle: replaced by Text with variant prop.
• DisplayText: replaced by Text with size="large".
• Layout: Layout.AnnotatedSection is now AnnotatedLayout.

Design tokens

Polaris 2.0 uses CSS custom properties for colors, spacing, and typography. The old Sass variables (e.g., $color-ink) are gone. Use var(--p-color-text) instead. This enables theming and dark mode support.

Layout primitives

New components like Page, Layout, BlockStack, InlineStack, and Grid provide more consistent spacing and responsiveness. The old Stack and Layout are deprecated.

For a full list, see the Polaris 2.0 changelog.

Which apps are affected

Polaris 2.0 affects any app that renders UI inside the Shopify admin using Polaris. That includes:

• Embedded admin apps built with Polaris and App Bridge.
• Custom apps for a single store that use Polaris components.
• POS extensions that use Polaris for UI.

If your app uses Polaris 1.x, you will need to migrate. Apps that use plain HTML/CSS without Polaris are not affected, but they may miss out on admin consistency.

Step-by-step migration path

Migrating to Polaris 2.0 requires planning. Follow these steps to minimize risk.

1. Audit your current usage

Run npm ls @shopify/polaris to see your version. Then search your codebase for deprecated components and props. Tools like polaris-codemods can automate some changes. Check the Polaris migration guide for a full list.

2. Set up a staging environment

Never migrate directly in production. Create a staging app with the same configuration as production. Install it on a development store. This lets you test without affecting live merchants.

3. Update dependencies incrementally

Upgrade Polaris and App Bridge together. Polaris 2.0 requires App Bridge 4.x. Update @shopify/app-bridge and @shopify/app-bridge-react to the latest versions. Then update Polaris to 2.x.

4. Replace deprecated components

Use the codemods where possible. For manual changes, refer to the migration guide. Common replacements:

• Stack → InlineStack or BlockStack
• TextStyle → Text
• DisplayText → Text with size="large"
• Layout.AnnotatedSection → AnnotatedLayout

5. Update design tokens

Replace Sass variables with CSS custom properties. For example, $color-ink becomes var(--p-color-text). Update your global CSS to use the new tokens.

6. Test thoroughly

Test every screen in your app. Check for visual regressions, broken layouts, and console errors. Use Shopify's Polaris playground to compare components.

7. Rollback plan

Keep the old version deployable. Use feature flags to switch between old and new UI. If something breaks, revert the flag. Monitor error tracking and user feedback after release.

Common breakages and how to test them

Here are issues we see often:

• Layout shifts: Stack removal can cause spacing issues. Test responsive breakpoints.
• Button variants: primary prop no longer works; buttons may appear default. Check all buttons.
• Token errors: Missing CSS variables cause unstyled components. Verify your CSS build includes Polaris tokens.
• App Bridge compatibility: Polaris 2.0 requires App Bridge 4.x. Mixing versions causes runtime errors.

Create a test checklist covering all interactive elements: forms, modals, banners, data tables, and navigation. Use automated visual regression tools if possible.

When to migrate vs rebuild

Migrating is usually faster if your app is small and uses standard Polaris components. Rebuilding may be better if:

• Your app heavily customizes Polaris with overrides.
• You are still on Polaris 1.x and have many deprecated patterns.
• You want to adopt new layout primitives from scratch.

Scope the work by counting components and estimating hours per component. A typical embedded app with 20 screens takes 2–4 weeks for migration and testing.

If you need help, our team offers Shopify app development services including Polaris migrations. We can audit your app, plan the migration, and execute it with minimal disruption.

Checklist before you release

• All Polaris 1.x components replaced or updated.
• Design tokens migrated to CSS custom properties.
• App Bridge updated to 4.x.
• Staging tested on development store.
• Visual regression tests passed.
• Rollback plan in place.
• Monitoring and error tracking enabled.

Polaris 2.0 is a significant update, but with a structured approach, you can migrate smoothly. Start with an audit, test in staging, and release with confidence.

Related reading

• Custom Shopify App Development Services: What You Get
• Global Catalog REST API Migration: Shopify App Owner's Plan