---
title: Versioning for web components
description: >-
  The Polaris web component library is versioned. Choose the release your app
  loads by naming it in the script tag, and control when your app moves to a new
  version.
api_version: v1.0
source_url:
  html: 'https://shopify.dev/docs/api/app-home/v1.0/web-components/versioning'
  md: 'https://shopify.dev/docs/api/app-home/v1.0/web-components/versioning.md'
api_name: app-home
---

# 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.

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.

***

## Adding 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 stable channel, `polaris-1.js`. Only name a specific release, like `polaris-1.0.js`, if you need to lock your app to exactly Polaris 1.0. To learn more, see [Stable releases and release candidates](#stable-releases-and-release-candidates).

#### 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

```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-1.js"></script>
</head>
```

##### Remix

```tsx
// 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-1.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](https://shopify.dev/docs/api/app-home/v1.0/apis).

#### React Router template

When you scaffold your app using [Shopify CLI](https://shopify.dev/docs/api/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.

Apps scaffolded by [Shopify CLI](https://shopify.dev/docs/api/shopify-cli) don't have a script tag to directly edit. Instead, the `AppProvider` component from [`@shopify/shopify-app-react-router`](https://www.npmjs.com/package/@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. Set the release you want in both places, and keep them the same: if they disagree, the browser downloads a file your app never runs.

##### React Router

```tsx
// app/routes/app.tsx
<AppProvider
  apiKey={apiKey}
  polarisUrl="https://cdn.shopify.com/shopifycloud/polaris-1.js"
>
  <Outlet />
</AppProvider>
```

##### Server configuration

```ts
// app/shopify.server.ts
const shopify = shopifyApp({
  // ...
  polarisUrl: 'https://cdn.shopify.com/shopifycloud/polaris-1.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. They require `@shopify/shopify-app-react-router` 2.1.0 or later.

***

## Type​Script packages

For TypeScript users, Shopify provides a companion npm library for Polaris web components types, available at [`@shopify/polaris-types`](https://www.npmjs.com/package/@shopify/polaris-types). You can install this library in your project using `yarn` or `npm`. Match the package version to the release your app loads, so that your types describe the components your app actually renders: a `1.0` build for `polaris-1.0.js`, or the newest `1.x` build if you follow `polaris-1.js`.

***

## Available 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-1.1.js` | Polaris 1.1, released in 2026 | Frozen as released |
| `polaris-1.0.js` | Polaris 1.0, released in 2025 | Frozen as released |
| `polaris.js` | The legacy unversioned entry point, currently 1.1 | Advances with each new stable 1.x release |

### Stable 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 URL instead, so moving to it is a change you make in your app's code: update the script tag to `polaris-1.1.js` for that release, or to `polaris-1.js` to follow the channel.

***