Versioning for web components
The Polaris web component library is versioned. Choose the release your app loads and control when your app moves to a new version. This reference documents the 2.0 release candidate.
For production, we recommend the stable channel, polaris-1.js. It always serves the newest stable release in Polaris 1, so bug fixes, accessibility improvements, and new components reach your app without a script-tag change. There's no stable 2.x release yet, and no polaris-2.js channel published.
Anchor to Adding Polaris to your appAdding Polaris to your app
You can pin any app to a particular version of the Polaris web component library, but the method you use depends on how you built it.
React Router template
When you scaffold your app using Shopify CLI, Polaris is added to your app automatically, set up with polaris-1.js to follow the newest stable release of Polaris version 1. The snippets on this page load polaris-2.0-rc.js instead, because this reference documents the 2.0 release candidate. A 2.0 bundle carries both the current admin theme and Admin Next, and follows whichever theme the merchant's admin is using. Apps load one bundle and don't need a flag or per-theme URL.
Apps scaffolded by Shopify CLI don't have a script tag to directly edit. Instead, the AppProvider component from @shopify/shopify-app-react-router renders the App Bridge and Polaris script tags for you, and your app's document responses carry a Link header that preloads the Polaris script. To build a React Router app against the release candidate this reference documents, set it in both places, and keep them the same: if they disagree, the browser downloads a file your app never runs.
React Router
// app/routes/app.tsx
<AppProvider
apiKey={apiKey}
polarisUrl="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js"
>
<Outlet />
</AppProvider>Server configuration
// app/shopify.server.ts
const shopify = shopifyApp({
// ...
polarisUrl: 'https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js',
});Both options are optional, and both default to the unversioned polaris.js entry point, so an app that sets neither behaves exactly as it does today. The unversioned entry point tracks the 1.x line and never serves 2.x. They require @shopify/shopify-app-react-router 2.1.0 or later.
Other frameworks
You can also manually add Polaris in any framework by adding the following script tag to your app's HTML head:
HTML
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js"></script>
</head>Remix
// 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-2.0-rc.js" />
</head>
</html>
);
}When you scaffold your app using Shopify CLI, Polaris is added to your app automatically, set up with polaris-1.js to follow the newest stable release of Polaris version 1. The snippets on this page load polaris-2.0-rc.js instead, because this reference documents the 2.0 release candidate. A 2.0 bundle carries both the current admin theme and Admin Next, and follows whichever theme the merchant's admin is using. Apps load one bundle and don't need a flag or per-theme URL.
Apps scaffolded by Shopify CLI don't have a script tag to directly edit. Instead, the AppProvider component from @shopify/shopify-app-react-router renders the App Bridge and Polaris script tags for you, and your app's document responses carry a Link header that preloads the Polaris script. To build a React Router app against the release candidate this reference documents, set it in both places, and keep them the same: if they disagree, the browser downloads a file your app never runs.
React Router
// app/routes/app.tsx
<AppProvider
apiKey={apiKey}
polarisUrl="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js"
>
<Outlet />
</AppProvider>Server configuration
// app/shopify.server.ts
const shopify = shopifyApp({
// ...
polarisUrl: 'https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js',
});Both options are optional, and both default to the unversioned polaris.js entry point, so an app that sets neither behaves exactly as it does today. The unversioned entry point tracks the 1.x line and never serves 2.x. They require @shopify/shopify-app-react-router 2.1.0 or later.
Anchor to TypeScript packagesType
For TypeScript users, Shopify publishes the @shopify/polaris-types package. Match the package version to the release your app loads, so that your types describe the components your app actually renders.
If you load polaris-2.0-rc.js, install @shopify/polaris-types@^2.0.0-rc.0. A plain ^2.0 range resolves to nothing while 2.0 is still a release candidate, because npm ranges exclude prereleases. That range tracks the release candidate as it accumulates changes, but it also accepts 2.0 and later 2.x stable releases once they publish, while polaris-2.0-rc.js keeps serving the release candidate. Pin the exact version to keep your types on the release candidate or to get reproducible installs, and update the script tag and the package together when you move to a stable release. If you follow polaris-1.js, install @shopify/polaris-types@^1.1.0.
Anchor to Available versionsAvailable versions
The following table shows the different options for configuring your script tag and the version of the library that is served. For production, we recommend the stable channel, polaris-1.js.
| Script tag | Serves | Notes |
|---|---|---|
polaris-1.js | The newest stable release in Polaris 1, currently 1.1 | Advances each time a new 1.x release goes stable |
polaris-2.0-rc.js | The 2.0 release candidate | The release candidate documented in this reference |
polaris-2.0.js | Polaris 2.0, once its release candidate is promoted | Not published yet; moving to it is a script-tag change |
polaris-1.1.js | Polaris 1.1 | Frozen as released |
polaris-1.0.js | Polaris 1.0 | Frozen as released |
polaris.js | The legacy unversioned entry point, currently 1.1 | Advances with each new stable 1.x release. Never serves 2.x |
Anchor to Stable releases and release candidatesStable releases and release candidates
Each stable release is also published at its own URL, like polaris-1.0.js and polaris-1.1.js. Published stable versions are immutable except for critical security fixes, ensuring that your app continues using the version of the library you tested against. If you need to control exactly when your app moves, name a specific version instead of the channel.
Promotion doesn't update the release candidate URL in place. The stable release publishes at its own polaris-2.0.js URL instead, so moving to it is a change you make in your app's code: update the script tag to polaris-2.0.js for that release.