Polaris 2.0: qué trajo el release candidate y cómo migrar tu app de Shopify
Actualización/ 18 min de lectura
Polaris 2.0 pasó de release candidate a estable el 22 de octubre. Qué cambió en la rc.1, qué URL usar, cómo probarla en una rama y qué migrar en tus componentes.
- Shopify
- Migración
- Apps de Shopify
En este artículo (8)
- Qué es Polaris y a qué se refiere Polaris 2.0
- Qué trae la 2.0, según el changelog de la rc.1
- Qué significa release candidate, y en qué quedó la de Polaris 2.0
- Cómo probar Polaris 2.0 en una rama
- Migración de componentes: Polaris React y lo que Polaris no controla
- Errores comunes
- Preguntas frecuentes
- Checklist
Polaris 2.0 es la nueva versión mayor de los Polaris web components, la librería con la que se construye la interfaz de las apps embebidas en el admin de Shopify. Su release candidate salió el 24 de septiembre de 2026, la rc.1 el 1 de octubre, y desde el 22 de octubre es estable: se carga con polaris-2.js.
Actualizado el 11 de noviembre de 2026: el release candidate ya no es la última versión. El 22 de octubre, Shopify publicó Polaris 2.0 como estable, en polaris-2.js y polaris-2.0.js. La URL del release candidate sigue respondiendo, pero se quedó en la 2.0.0-rc.3. Abajo tienes lo que trajo la rc.1, qué significa ese paso y cómo probar la versión estable en una rama.
Qué es Polaris y a qué se refiere Polaris 2.0
Polaris es el sistema de diseño de Shopify para el admin. En la interfaz principal de una app embebida, lo que Shopify llama App Home, Polaris hoy son web components: elementos HTML con el prefijo s-, como <s-page>, <s-section> o <s-button>. Los registra un solo script que tu app carga desde la CDN de Shopify, así que no se importan: se escriben directamente en el HTML o en el JSX. En npm no hay un paquete con los componentes; lo que se publica ahí son los tipos de TypeScript, @shopify/polaris-types.
Polaris 2.0 es la segunda versión mayor de esa librería: el archivo polaris-2.js de la CDN y @shopify/polaris-types 2.0.0. No es una versión de Polaris React. El paquete @shopify/polaris tiene en npm el aviso «Polaris React is deprecated and no longer maintained», su última versión es la 13.9.5, de marzo de 2025, y lo que dibuja no recibe el estilo nuevo aunque la página cargue Polaris 2.0.
La numeración importa porque, desde el 31 de agosto de 2026, la CDN de Polaris sigue versionado semántico: las versiones mayores pueden traer cambios incompatibles, las menores traen componentes, correcciones y ajustes visuales compatibles, y los parches de seguridad pueden llegar también a mayores anteriores. Los tipos usan la misma versión mayor que la CDN. La primera menor con este esquema fue Polaris 1.1, estable desde el 22 de septiembre, y la 2.0 es la primera mayor.
¿Por qué una mayor? Por el admin. Según el anuncio del release candidate del 24 de septiembre de 2026, el nuevo diseño del admin empezó a llegar a los comerciantes de forma progresiva el 15 de septiembre. La guía Update your app for Polaris 2 explica el mecanismo: el admin indica a través de App Bridge qué estilo usar, y Polaris 2.0 lleva los dos estilos y elige en tiempo de ejecución. En una tienda con el diseño nuevo, tus componentes toman el color, la tipografía, el espaciado y los iconos nuevos; en una tienda con el diseño anterior, se ven igual que con polaris-1.js. Polaris 1 no contiene el estilo nuevo, así que una app que se quede ahí conserva el aspecto anterior en cualquier tienda.
Dos cosas que no cambian: las admin UI extensions y las App Home UI extensions se adaptan solas al diseño de cada comerciante, sin tocar su código. Y si tu app tiene el distintivo Built for Shopify, el anuncio le da hasta el 1 de mayo de 2027 para que su App Home coincida con el estilo visual del admin.
Qué trae la 2.0, según el changelog de la rc.1
El 1 de octubre de 2026, Shopify publicó What's new in Polaris 2.0.0-rc.1. Su resumen: más componentes alineados con el nuevo estilo del admin, correcciones de layout y de manejo de eventos, y montaje y actualizaciones más rápidos. Estos son todos los cambios que lista, sin añadir ninguno. El changelog nombra los componentes en PascalCase (Table, Section); en la tabla van con su etiqueta, y cada etiqueta pasó el validador de Polaris de Shopify.
| Componente | Cambio en la rc.1 | Grupo del changelog |
|---|---|---|
s-table | Coincide con el diseño actualizado del admin. | Componentes |
s-tooltip | Se puede colocar en el slot supplemental de s-section. | Componentes |
s-section | Tarjetas de igual alto dentro de la misma s-grid. | Componentes |
s-select | Mide lo mismo de alto que s-text-field y los demás campos. | Componentes |
s-badge | Forma de píldora en celular. | Componentes |
s-banner | Mejor contraste en el título. | Componentes |
s-color-picker | Corregida la sombra del área de saturación en las esquinas. | Componentes |
s-section | En pantallas angostas, la acción principal baja debajo de la tarjeta en vez de apretar el encabezado. | Layout |
s-section | Encabezados y subencabezados con menos espacio entre sí; en el aside, los encabezados usan el color de texto por defecto. | Layout |
s-menu | Los iconos usan el color secundario en reposo. | Layout |
s-page | Corregido el estilo de las secciones del aside. | Layout |
s-page y s-section | Las acciones secundarias ya no pierden el icono de despliegue si su menú o su texto se añaden después de montar. | Layout |
s-section anidada | La primera ya no queda más abajo que otros primeros hijos. | Layout |
| Acciones en slots | Ya no desaparecen cuando se inyecta marcado en un elemento ya conectado. | Layout |
globalThis.polaris | Su estado ya no se pierde si la página carga el bundle más de una vez. | Fiabilidad |
s-modal | Sus acciones disparan un click que burbujea aunque tengan commandFor. | Fiabilidad |
s-text-field | Los clics en el accesorio llegan a los onClick de React. | Fiabilidad |
| Rendimiento | Montaje y actualizaciones más rápidos, sobre todo en páginas sin React, y menos re-renders por atributos ajenos en s-choice-list, s-menu, s-modal, s-select y los pickers. | Rendimiento |
La entrada no anuncia componentes nuevos ni retirados: son ajustes sobre componentes que ya existían. Lo nuevo de verdad está en el anuncio del 24 de septiembre (los dos estilos en un solo bundle) y en el aspecto, que cambia aunque tu código no cambie. En npm hay además una rc.2 (5 de octubre) y una rc.3 (9 de octubre) de los tipos, pero no encontramos una entrada propia del changelog para ninguna de las dos.
Desliza la figura para verla completa
Qué significa release candidate, y en qué quedó la de Polaris 2.0
En Semantic Versioning 2.0.0, una versión con un guion después del número, como 2.0.0-rc.1, es una prerelease: según la especificación, es inestable y puede no cumplir los requisitos de compatibilidad de la versión normal. El orden de precedencia de su ejemplo pone alpha antes que beta, beta antes que rc, y cualquier rc antes que la versión sin sufijo. En la práctica, release candidate quiere decir «esto es lo que pensamos publicar como estable: pruébalo».
Polaris no usa alpha ni beta. Según la entrada sobre versionado semántico, todo cambio pasa primero por un build release candidate, pensado para desarrollo y pruebas, que acumula mejoras durante su ventana y se actualiza en la misma URL. Los canales estables reciben el cambio después de esa fase. La 2.0 siguió ese camino:
- 23 y 24 de septiembre:
@shopify/polaris-types2.0.0-rc.0 en npm y el anuncio del release candidate, conpolaris-2.0-rc.js. - 1 de octubre: la rc.1 y la entrada del changelog de la tabla de arriba.
- 5 y 9 de octubre: la rc.2 y la rc.3 de los tipos.
- 21 y 22 de octubre: la 2.0.0 en npm y Polaris 2.0 estable en la CDN.
Desliza la figura para verla completa
Un detalle que deja claro la documentación de versionado de los web components: la promoción no mueve la URL del RC. La versión estable se publica en su propia URL, así que pasar a ella es un cambio en tu código. Lo comprobamos el 11 de noviembre: descargamos cada archivo con curl y lo cargamos sin red en un Chromium local para leer la versión que reporta.
| Script | Sirve hoy (11 nov 2026) | ¿Se actualiza solo? |
|---|---|---|
polaris.js | 1.1.0 | Sí, dentro de la 1.x. Nunca pasa a la 2.x. |
polaris-1.js | 1.1.0 | Sí, con cada 1.x estable. |
polaris-2.0-rc.js | 2.0.0-rc.3 | Ya no: la promoción no lo llevó a la estable. |
polaris-2.js | 2.0.0 | Sí, con cada 2.x estable. Es el canal que la documentación recomienda para producción. |
polaris-2.0.js | 2.0.0 | No: queda fija, salvo parches de seguridad críticos. |
polaris-2.1-rc.js | No existe (404) | Todavía no hay RC de la 2.1. |
Con los tipos pasa algo parecido, y es donde más fácil es equivocarse. Un rango normal de npm no acepta prereleases:
$ npm view @shopify/polaris-types dist-tags
{ latest: '2.0.0', next: '2.0.0-rc.3' }
$ npm view "@shopify/polaris-types@^2.0.0" version
2.0.0
dist-tagsmuestra las dos etiquetas del paquete:latestapunta a la 2.0.0 estable ynextse quedó en la última RC.- El rango
^2.0.0resuelve solo a la 2.0.0. De la rc.0 a la rc.3 no entran: npm excluye las prereleases de un rango normal. - Para seguir un RC, la documentación pide
^2.0.0-rc.0. Lo comprobamos con el semver de npm 11.11.1: ese rango acepta la 2.0.0-rc.3, la 2.0.0 y la 2.1.0, así que fija la versión exacta si quieres quedarte en el RC.
Cómo probar Polaris 2.0 en una rama
Con la 2.0 ya estable, la prueba se hace con polaris-2.js. El procedimiento es el que el anuncio pedía para el RC, y te sirve para el siguiente: cuando salga un RC de la 2.1, cambia la URL por polaris-2.1-rc.js y los tipos por ^2.1.0-rc.0. Trabaja en una rama para que producción siga en Polaris 1 hasta que termines.
git switch -c polaris-2
npm install --save-dev @shopify/polaris-types@^2.0.0
shopify store create dev --name polaris-2-qa --feature-preview new_admin_design
shopify app dev
git switch -c polaris-2crea la rama. Todo lo que sigue vive ahí hasta el merge.- Instala los tipos de la 2.0 como dependencia de desarrollo. Según la documentación,
^2.0.0va conpolaris-2.js; si fijaspolaris-2.0.js, usa~2.0.0. shopify store create devcrea una tienda de desarrollo, y--feature-preview new_admin_designle activa la vista previa «Shopify admin's new design». La vista previa solo se elige al crear la tienda, y cada tienda admite una.--namees obligatorio si corres el comando sin interacción.shopify app devlevanta tu app en la tienda que elijas. Repite la prueba en una tienda sin la vista previa para ver el diseño anterior.
No corrimos los dos comandos de shopify: piden iniciar sesión en una cuenta de Shopify. Su sintaxis viene de la documentación del CLI.
Ahora cambia la URL. Si tu app sale de la plantilla de React Router, no tiene una etiqueta script propia: la renderiza AppProvider, y la configuración del servidor añade un encabezado Link que la precarga. Cambia los dos lugares, con el mismo valor:
// app/routes/app.tsx
<AppProvider
apiKey={apiKey}
polarisUrl="https://cdn.shopify.com/shopifycloud/polaris-2.js"
>
<Outlet />
</AppProvider>
// app/shopify.server.ts
const shopify = shopifyApp({
// ...
polarisUrl: 'https://cdn.shopify.com/shopifycloud/polaris-2.js',
});
polarisUrlenAppProviderdecide qué script de Polaris renderiza la app.polarisUrlenshopifyAppdecide qué archivo precarga el encabezadoLink. Si los dos valores difieren, el navegador precarga un bundle y la app carga otro.- Las dos opciones necesitan
@shopify/shopify-app-react-router2.1.0 o posterior. Sin ellas, de la 2.1.0 a la 3.x el valor por defecto espolaris.js, es decir, Polaris 1. Según su changelog, la 4.0.0, publicada el 21 de octubre, cambia el valor por defecto apolaris-2.js.
Si tu app escribe su propia etiqueta, cambia solo la URL y deja Polaris después de App Bridge, para que App Bridge publique la señal del admin antes de que Polaris arranque:
<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>
- La etiqueta
metale dice a App Bridge qué app se está cargando. app-bridge.jsno se versiona con Polaris: su URL no lleva número y siempre carga la última versión.polaris-2.jsva después y es la única etiqueta de Polaris de la página. Para probar el RC, el anuncio ponía aquípolaris-2.0-rc.js.
Con la URL cambiada, monta una página de prueba con los componentes que tocó la rc.1 y ábrela en las dos tiendas. Esta pasa el validador de Polaris de Shopify con los tipos 1.0.1 y 2.0.0:
export function Polaris2Smoke() {
return (
<s-page heading="Polaris 2 smoke test">
<s-button slot="primary-action" variant="primary">Save</s-button>
<s-banner tone="info" heading="Polaris 2.0">
Open this page in both admin designs.
</s-banner>
<s-grid gridTemplateColumns="1fr 1fr" gap="base">
<s-section heading="Sync">
<s-icon slot="supplemental" type="info" interestFor="sync-tip"></s-icon>
<s-tooltip slot="supplemental" id="sync-tip">Runs every hour.</s-tooltip>
<s-badge tone="success">Active</s-badge>
</s-section>
<s-section heading="Settings">
<s-select label="Status" name="status">
<s-option value="active">Active</s-option>
<s-option value="draft">Draft</s-option>
</s-select>
<s-text-field label="Title" name="title"></s-text-field>
</s-section>
</s-grid>
<s-section heading="Products" padding="none">
<s-table>
<s-table-header-row>
<s-table-header listSlot="primary">Product</s-table-header>
<s-table-header listSlot="inline">Status</s-table-header>
</s-table-header-row>
<s-table-body>
<s-table-row>
<s-table-cell>Cotton t-shirt</s-table-cell>
<s-table-cell><s-badge tone="success">Active</s-badge></s-table-cell>
</s-table-row>
</s-table-body>
</s-table>
</s-section>
</s-page>
);
}
s-pagecon uns-buttonenslot="primary-action": la acción principal que el admin coordina con su barra de título.s-bannerconheading: la rc.1 mejoró el contraste de ese título.s-gridcon doss-sectionde contenido distinto: desde la rc.1, las tarjetas de una misma rejilla tienen el mismo alto.s-iconys-tooltipenslot="supplemental": el tooltip ya se puede colocar en ese slot, yinterestForune el icono con su tooltip.s-badge: en celular toma forma de píldora.s-selectjunto as-text-field: ahora miden lo mismo de alto.s-tabledentro de unas-sectionconpadding="none": la tabla con el diseño actualizado, de borde a borde.
La renderizamos sin red en un Chromium local con las copias de polaris-1.js, polaris-2.0-rc.js y polaris-2.js, a 900 y 375 píxeles de ancho, sin errores en la consola. Fuera del admin, Polaris 2.0 usa por defecto el estilo nuevo, y así fue: con polaris-2.js, el título de la página creció y los encabezados de sección salieron de la tarjeta. Fuera del admin tampoco hay App Bridge, así que esta prueba no sustituye a la de las dos tiendas.
Para saber qué bundle cargó tu app, abre la consola del navegador con el marco de tu app seleccionado:
globalThis.polaris?.version
- En nuestra prueba devolvió
'2.0.0'conpolaris-2.js,'2.0.0-rc.3'con la URL del RC y'1.1.0'conpolaris.jsopolaris-1.js. Esa propiedad no aparece en la documentación: úsala para depurar, nunca en el código de la app. Lo documentado es revisar el panel de red, donde debe haber una sola petición a un archivopolaris-*.js.
Migración de componentes: Polaris React y lo que Polaris no controla
Polaris 2.0 solo cambia lo que dibuja Polaris. Lo demás se queda como está, y ahí está el trabajo de la migración: los componentes de Polaris React que aún tengas y tu propio CSS.
Si tu app todavía usa Polaris React
Lo que renderiza @shopify/polaris conserva el aspecto anterior, así que una página que mezcle los dos sistemas se verá con dos estilos. La guía de migración desde Polaris React propone hacerlo por partes, una página o familia de rutas a la vez, en este orden: el armazón de la página (Page, Card, Layout y sus acciones); lo visual (Badge, Banner, Text, Icon); botones, enlaces, menús, modales y popovers; formularios; y al final tablas, filtros y acciones masivas. El anuncio del RC coincide: empieza por Page, Section y Button, que son los que más cambian el aspecto. Este es el ejemplo de la guía. Antes:
import {Card, Page, Text} from '@shopify/polaris';
export function ProductsPage({onCreateProduct}) {
return (
<Page
title="Products"
primaryAction={{content: 'Create product', onAction: onCreateProduct}}
>
<Card>
<Text as="h2" variant="headingSm">All products</Text>
<Text as="p">Manage the products available through your app.</Text>
</Card>
</Page>
);
}
- El componente importa
Card,PageyTextde@shopify/polaris, el paquete obsoleto. Pagerecibe el título y la acción principal como props de React.Cardagrupa el contenido, y el encabezado es unTextconvariant="headingSm".
Después, con web components:
export function ProductsPage({onCreateProduct}) {
return (
<s-page heading="Products">
<s-button
slot="primary-action"
variant="primary"
onClick={onCreateProduct}
>
Create product
</s-button>
<s-section heading="All products">
<s-paragraph>
Manage the products available through your app.
</s-paragraph>
</s-section>
</s-page>
);
}
- No hay
import: los elementoss-los registra el script de la CDN. titlepasa a serheadingens-page.- La acción principal deja de ser un objeto y pasa a ser un
s-buttonconslot="primary-action"yvariant="primary". Tiene que ser uno solo. - No existe
s-card: la tarjeta con encabezado es unas-sectionconheading, y el texto, uns-paragraph. Este bloque pasó el validador con los tipos 1.0.1 y 2.0.0.
Otras reglas de la guía que ahorran tiempo: los props de varias palabras van en camelCase (accessibilityLabel, commandFor) y los slots en kebab-case; url pasa a ser href; los modales, popovers y menús se abren con commandFor en lugar de un estado open controlado. Los selectores .Polaris-* no llegan dentro de un web component, porque el shadow DOM no los deja pasar. Si renderizas los web components desde React con campos controlados, necesitas React 19. Y si tu app define una Content Security Policy, añade https://cdn.shopify.com a script-src.
Lo que Polaris no controla
La guía de Polaris 2 pide revisar tres cosas que la librería no toca. El CSS que lee propiedades de Polaris o copia valores de @shopify/polaris-tokens se queda con la paleta anterior: cámbialo por tus propios tokens o por componentes de Polaris. Si tu app fija la fuente Inter, mantiene la tipografía vieja; el admin nuevo usa ShopifyInter, y Polaris 2.0 carga la que corresponde. Y lo que construiste a mano para parecerse a Polaris (tarjetas, badges, banners, estados vacíos) se va a notar junto a los componentes nuevos.
Hay una cuarta que no depende de la versión de Polaris: el admin nuevo pone elementos flotantes sobre la parte baja de tu app, como la barra de Sidekick o la navegación en celular. App Bridge publica su altura en una variable CSS y ya añade el relleno al <body>, así que solo te afecta si tienes elementos fijos abajo:
.sticky-footer {
position: fixed;
bottom: var(--shopify-safe-area-inset-bottom, 0px);
}
.sticky-footeres un nombre de ejemplo: aplícalo a tu pie fijo o a tu botón flotante.position: fixedes lo que ya tenías.bottomusa--shopify-safe-area-inset-bottom, la altura que reporta App Bridge, con0pxde respaldo cuando no flota nada. La documenta la Environment API.
Desliza la figura para verla completa
Después, recorre los flujos principales de tu app en las dos tiendas, incluidos los estados vacíos, los de error y las pantallas que solo aparecen tras una configuración larga.
Errores comunes
- Esperar que
polaris.jsllegue a la 2.0. No va a pasar: la URL sin número sigue la 1.x para siempre. El cambio de mayor siempre es explícito. - Quedarse en
polaris-2.0-rc.js. La promoción no la movió: hoy sirve la 2.0.0-rc.3. Pasa apolaris-2.js, o apolaris-2.0.jssi quieres fijar la versión. - Cambiar
polarisUrlsolo enAppProvider. El encabezadoLinksigue precargando el otro bundle. Cambia tambiénshopifyApp. - Añadir una etiqueta
scriptpropia en una app de la plantilla. Serían dos bundles, y la documentación dice que eso hace fallar la app. En nuestra prueba fuera del admin no hubo error visible y ganó el segundo bundle, así que revisa el panel de red: el problema puede no avisar. - Subir
@shopify/shopify-app-react-routera la 4.x sin mirar Polaris. Si no fijastepolarisUrl, la app pasa a cargarpolaris-2.jsy cambia de aspecto en ese despliegue. Para quedarte en la 1, su changelog indica ponerpolaris-1.jsen los dos lugares. - Usar
^2.0.0en los tipos mientras pruebas un RC. npm salta las prereleases. Para un RC, usa^N.M.0-rc.0o la versión exacta. - Probar solo con el diseño nuevo. Durante el despliegue progresivo hay comerciantes en los dos diseños, y tu app tiene que verse bien en ambos.
- Migrar una página a medias. Si en la misma vista conviven Polaris React y web components, con Polaris 2.0 se verán dos estilos.
Preguntas frecuentes
¿Polaris 2.0 sigue en release candidate?
No. El release candidate se anunció el 24 de septiembre de 2026 y la versión estable salió el 22 de octubre. Hoy la URL recomendada es polaris-2.js. La del RC sigue respondiendo, con la 2.0.0-rc.3, pero ya no recibe cambios.
¿Mi app va a cambiar de aspecto sola?
No, mientras cargue polaris.js, polaris-1.js o una versión fija de la 1.x. Hay una excepción: con @shopify/shopify-app-react-router 4.0.0 o posterior y sin polarisUrl, la plantilla carga polaris-2.js por defecto. Las extensiones del admin sí se adaptan solas al diseño de cada tienda.
¿Tengo que dejar Polaris React para usar Polaris 2.0?
Sí, en todo lo que quieras con el estilo nuevo. Polaris 2.0 solo cambia los web components; lo que renderiza @shopify/polaris conserva el aspecto anterior, y el paquete está marcado como obsoleto en npm. Migra por páginas, empezando por Page, Section y Button.
¿Hay fecha límite para migrar?
Para las apps con Built for Shopify, sí: hasta el 1 de mayo de 2027 para que su App Home coincida con el estilo visual del admin. Para el resto, las fuentes que revisamos no dan una fecha. Polaris 1 sigue disponible en polaris-1.js y, según el esquema de versiones, puede recibir parches de seguridad.
Checklist
- Tu app usa Polaris web components, y lo que queda de
@shopify/polarisestá en una lista con fecha. - Trabajas en una rama, con producción todavía en Polaris 1.
- La URL es
polaris-2.js(opolaris-2.0.jssi la fijas), nopolaris-2.0-rc.js. - En apps de la plantilla,
polarisUrltiene el mismo valor enAppProvidery enshopifyApp. - Hay una sola etiqueta de Polaris, después de
app-bridge.js, y el panel de red muestra una sola petición. @shopify/polaris-typesestá en^2.0.0, a juego con la URL.- Revisaste el CSS con tokens de Polaris, las fuentes fijas y los componentes hechos a mano.
- Los elementos fijos abajo usan
var(--shopify-safe-area-inset-bottom, 0px). - Probaste los flujos principales en una tienda con
new_admin_designy en otra sin él.
Si además mantienes descuentos en Shopify Scripts, la otra migración pendiente es pasar de Shopify Scripts a Functions de descuento. Y si no tienes claro que tu app necesite una interfaz embebida, lee qué es realmente una app a medida de Shopify: no todas la necesitan.
Si tu app también vive en el checkout, mira cómo agregar un campo extra con una checkout UI extension.
¿Viste esto en Instagram? Comenta POLARIS en el Reel y te mando la guía.
Escrito por

Publicado el 11 de noviembre de 2026 · actualizado el 18 de noviembre de 2026