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 Polaris v2.0.
For production, we recommend the stable channel for your major version, polaris-N.js, like polaris-2.js. It always serves the newest stable release in Polaris N, so bug fixes, accessibility improvements, and new components reach your app without a script-tag change. A major version's channel is published with its first stable release, so it isn't available while that major version has only a release candidate.
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.
The snippets below load the file for this reference's version: a release candidate's own file, polaris-N.M-rc.js, like polaris-2.0-rc.js, or, for a stable version, the stable channel for its major version, polaris-N.js, like polaris-2.js. To lock your app to exactly one release, load polaris-N.M.js, like polaris-2.0.js. To learn more, see Available versions.
A 2.0 bundle carries both the current Shopify admin appearance and the updated one, and follows whichever appearance the merchant's Shopify admin is using. Apps load one bundle and don't need a flag or per-appearance URL.
HTML
To add Polaris to an app built with any framework, add the following script tags to your app's HTML head. Load App Bridge alongside Polaris: App Bridge connects your app to Shopify admin, and the shopify-api-key meta tag tells it which app is loading.
HTML
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.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/app-bridge.js" />
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.js" />
</head>
</html>
);
}App Bridge isn't versioned with Polaris, so its script tag has no version in the URL and always loads the latest App Bridge. To learn what App Bridge provides, see App Bridge APIs.
React Router template
Apps that you scaffold using Shopify CLI include Polaris automatically. Which release they load by default depends on their version of @shopify/shopify-app-react-router.
The AppProvider component from @shopify/shopify-app-react-router renders the App Bridge and Polaris script tags for the routes that it wraps, and your app's document responses carry a Link header that preloads the Polaris script. To choose the Polaris release your app loads, set it in both places, and keep them the same: if they disagree, the browser downloads a file your app never runs.
The examples use the file names of the TypeScript template. In the JavaScript template, the same files end in .jsx instead of .tsx and .js instead of .ts, like app/routes/app.jsx and app/shopify.server.js.
React Router
// app/routes/app.tsx
<AppProvider
apiKey={apiKey}
polarisUrl="https://cdn.shopify.com/shopifycloud/polaris-2.js"
>
<Outlet />
</AppProvider>Server configuration
// app/shopify.server.ts
const shopify = shopifyApp({
// ...
polarisUrl: 'https://cdn.shopify.com/shopifycloud/polaris-2.js',
});Both options are optional, and they require @shopify/shopify-app-react-router 2.1.0 or later. If you set neither, then the default depends on the package's major version. In versions 2.1.0 to 3.x, both default to the unversioned polaris.js entry point. The unversioned entry point tracks the 1.x line and never serves 2.x. In version 4.0.0 and later, both default to polaris-2.js. To stay on Polaris 1 with version 4.0.0 or later, set both options to polaris-1.js. To learn which release each entry point serves, see Available versions. To learn when the default changed, see the @shopify/shopify-app-react-router changelog.
Some versions of the template also load Polaris on the login page, app/routes/auth.login/route.tsx (route.jsx in the JavaScript template), with a script tag or an AppProvider of its own. polarisUrl in app/routes/app.tsx doesn't apply to that page, so the login page can load a different release from the rest of your app. If your app has this route, then load Polaris there with a script tag that uses the same URL as polarisUrl. The login page is a separate document from the routes that AppProvider wraps, so this tag doesn't load a second bundle. Don't use AppProvider on the login page: from version 2.0.0, it always loads App Bridge too, and the login page opens outside the Shopify admin.
To add Polaris to an app built with any framework, add the following script tags to your app's HTML head. Load App Bridge alongside Polaris: App Bridge connects your app to Shopify admin, and the shopify-api-key meta tag tells it which app is loading.
HTML
<head>
<meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.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/app-bridge.js" />
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.js" />
</head>
</html>
);
}App Bridge isn't versioned with Polaris, so its script tag has no version in the URL and always loads the latest App Bridge. To learn what App Bridge provides, see App Bridge APIs.
Anchor to TypeScript packagesType Script packages
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.
Pick the range from the script tag:
- If you load a stable channel,
polaris-N.js, install@shopify/polaris-types@^N.0.0, like^2.0.0forpolaris-2.js. - If you load a stable release,
polaris-N.M.js, install@shopify/polaris-types@~N.M.0, like~1.1.0forpolaris-1.1.js, so the package stays on that release like the script tag. - If you load a release candidate,
polaris-N.M-rc.js, install@shopify/polaris-types@^N.M.0-rc.0, like^2.0.0-rc.0forpolaris-2.0-rc.js. A plain^N.M.0range skips release candidates, because npm ranges exclude prereleases. The-rc.0range also accepts the stable release and later N.x releases once they publish, so pin the exact version to keep your types on the release candidate.
For reproducible installs, pin the exact version instead. Update the script tag and the package together when you move to a new release.
Anchor to Available versionsAvailable versions
The following table shows the script tags that the CDN publishes, by pattern, and the version of the library that each one serves. N is a major version and M is a minor version. For production, we recommend the stable channel for your major version, like polaris-2.js.
| Script tag | Serves | Notes |
|---|---|---|
polaris-N.js, like polaris-2.js | The newest stable release in Polaris N | The stable channel. Advances each time a new N.x release goes stable. Published with the first stable N.x release |
polaris-N.M.js, like polaris-1.1.js | Polaris N.M | Frozen as released |
polaris-N.M-rc.js, like polaris-2.0-rc.js | The N.M release candidate | Can change until it's promoted. Promotion doesn't move it to the stable release |
polaris.js | The newest stable release in Polaris 1 | The legacy unversioned entry point. Advances with each new stable 1.x release. Never serves 2.x or later |
Anchor to Stable releases and release candidatesStable releases and release candidates
Each stable release is also published at its own URL, polaris-N.M.js, like 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.
When a release candidate goes stable, its reference becomes the reference for the stable release, and the release candidate's reference is no longer published separately. If you bookmarked the release candidate's reference, then use the stable release's reference instead.
Promotion doesn't update the release candidate URL in place. The stable release publishes at its own URL instead, so moving to it is a change you make in your app's code. For example, if your app loads the 2.0 release candidate, polaris-2.0-rc.js, update the script tag to polaris-2.0.js for that release, or to polaris-2.js to follow the channel.
Anchor to Check which version your app loadsCheck which version your app loads
A channel, like polaris-2.js, or the unversioned polaris.js doesn't show which release it serves. To check the script that your app loads and the release that it runs, open your app in the Shopify admin, and then open your browser's developer tools:
- In the Network panel, filter the requests by
polaris. The file name in the request URL is the script that your app loads, likepolaris-2.js. If your app also loads Polaris on a page outside the Shopify admin, such as a login page, then open that page and check it too. - In the Console panel, select your app's frame as the JavaScript context, and then run
polaris.version. The result is the exact release that your app runs, like"2.0.0". For a release candidate, the result includes the build number, like"2.0.0-rc.3".
The @shopify/polaris-types version can be different from this result. The types package publishes a new version only when the types change, so a release can have no types package with the same version. To pin your types, install the newest published @shopify/polaris-types version on the same release line.