The important bit is this. Your app won't update itself. Nothing breaks today, but nothing changes either, so someone has to make a decision.

What Shopify has actually changed

Shopify is giving the admin a new frame, new navigation and a new visual appearance. Polaris 2.0 updates the web components so apps match that new look. Shopify's own words are that it lets your app match "the look and feel" of the new admin.

There's a neat trick in how it works. Polaris 2.0 contains both the current appearance and the new one, and picks the right one at runtime based on signals from the admin. You don't need to write any code to switch between them. Merchants still on the current admin see the current look, and those on the new one see the new look.

Polaris 1 doesn't get any of the new styling. Apps on Polaris 1, and apps still using the older React @shopify/polaris components, keep the current appearance whatever the admin around them looks like.

Why your app stays where it is

Polaris is loaded from Shopify's CDN using a script tag, and the version you get depends on which address that tag points to. Shopify's versioning docs set it out like this:

  • polaris.js is the old unversioned address. It tracks the latest 1.x release and will never serve 2.x.
  • polaris-1.js serves the newest 1.x release, currently 1.1.
  • polaris-2.js serves the newest 2.x release, currently 2.0. Shopify recommends this one for production.
  • polaris-2.0.js pins you to exactly 2.0, so later 2.x releases won't change anything until you choose.

So if your app was built a while ago and points at polaris.js, it'll stay on Polaris 1 indefinitely. That's deliberate on Shopify's part. It means nobody's app suddenly changes underneath them, which is a sensible way to roll out a redesign. It also means the update is on you.

Shopify hasn't given an end date for Polaris 1 and the changelog doesn't mark this as required. There's no deadline to panic about. But if the admin around your app changes and your app doesn't, your staff will be looking at something that feels bolted on, and that's the kind of thing that's easier to sort on your own timetable than in a rush later.

What the update involves

For a lot of apps, the first step is genuinely small. If your app loads Polaris with its own script tag, you change the address to polaris-2.js (loaded after App Bridge). If it's built on Shopify's React Router template, you set the same Polaris address in two places, the AppProvider and the shopifyApp server configuration, and you need version 2.1.0 or later of the React Router package. TypeScript projects also need the matching @shopify/polaris-types package.

That's the easy part. Shopify's migration guide then lists the things that actually take time, and this is where older or heavily customised apps can get fiddly:

  • Only load one Polaris bundle. Shopify warns that two scripts cause an error, so an app that adds its own tag on top of the template's one needs tidying.
  • Old React components. Anything still using the React @shopify/polaris library won't pick up the new look and needs moving over to the web components.
  • Custom CSS. Styles that use Polaris token values need removing or replacing.
  • Fonts. The updated admin uses ShopifyInter, so a hardcoded font stack will keep the old type.
  • Home-made lookalikes. Hand-built cards, badges, banners and empty states that copy the Polaris style will need restyling.
  • Things fixed to the bottom of the screen. These need a small CSS change so they sit above the admin overlay.

In short, an app built cleanly on Polaris web components is a quick job. An app that's been patched by three different people over four years, with its own styling layered on top, is more of a proper piece of work. Neither is a disaster. You just want to know which one you've got before you start.

Test both looks, not just the new one

Because Polaris 2.0 serves two appearances, you need to check your app in both. Shopify lets developers create a development store with the new admin design switched on as a feature preview, and any other development store shows the current design. Walk through your main screens in each, including the awkward ones: empty states, error messages and long setup screens. Those are usually where the odd layout problem hides.

What I'd do this week

Nothing dramatic. Just three things:

  • Make a list of your custom apps. Private apps, staff tools, anything embedded in your admin that you paid someone to build. If that list doesn't exist yet, it's a useful thing to have anyway.
  • Find out which Polaris address each one loads. A developer can tell you in a few minutes by looking at the code.
  • Decide on timing. If an app is simple, update it now while you're thinking about it. If it's complicated, get it scoped and scheduled rather than left to drift.

If you don't know who built an app, or the person who did has moved on, that's worth fixing in its own right. Something that runs inside your store admin really should have somebody looking after it.

Where we can help

We build and look after custom Shopify apps and integrations, including private apps and staff tools. If you'd like us to check which of your apps need the Polaris 2.0 update and tell you plainly how big a job it is, we're happy to do that. And if you've got an app nobody's maintaining at the moment, our software support and maintenance plans are designed for exactly that.

Drop us a line through the contact page and tell us what you've got. We'll give you a straight answer.

Cheers, Rob