11 · Admin Apps · Polaris · App Bridge

Esta sección no introduce comandos obligatorios nuevos — el scaffold de la app ya se generó en la sección 02. El plan de implementación vive en ~/proyectos/shopify/brew-atlas/brew-atlas-app/app/PLAN.md. Los comandos de arriba son referencia para scaffoldear en otro directorio.

Qué es y por qué existe

Cuando un comerciante instala una app de Shopify, la espera es que esa app aparezca integrada en su panel de administración — no que lo redirija a un sitio externo con otra interfaz. Las apps embebidas cumplen esa expectativa: se renderizan dentro del Admin de Shopify en una región controlada por Shopify, con la barra de navegación y el aspecto visual del Admin como contexto.

Técnicamente, la app embebida es una aplicación web estándar (en este caso, un servidor Node.js con React Router v7) que Shopify carga dentro de un <iframe>. El comerciante navega a https://admin.shopify.com/store/tu-tienda/apps/tu-app y ve tu interfaz dentro del shell del Admin. La barra lateral de Shopify, la barra superior, el usuario autenticado — todo eso es del Admin. Tu app ocupa el contenido central.

La razón por la que Shopify prefiere este modelo sobre “apps standalone” es la confianza del comerciante: el comerciante sabe que está dentro de Shopify. No hay redirecciones a dominios desconocidos para operaciones críticas. Shopify también puede aplicar su Content Security Policy al iframe para prevenir ciertos ataques.

El stack en 2026

El template oficial del CLI genera un proyecto con esta pila:

• Node.js backend con React Router v7 como framework full-stack
• Polaris 13.x como sistema de diseño — el mismo que usa el Admin de Shopify
• App Bridge (web components) para acciones nativas del Admin: modales, toasts, resource pickers, navegación
• Session token authentication: el Admin inyecta un JWT en la app; tu servidor lo verifica e intercambia por un access token para llamar al Admin GraphQL API
• Prisma (incluido en el template por defecto) para persistencia local

Generar el scaffold

El CLI de Shopify genera todo el boilerplate con un comando. Desde ~/proyectos/shopify/brew-atlas/ (o cualquier directorio donde quieras crear el scaffold):

npm init @shopify/app@latest

El CLI pregunta el template — elegí react-router (o remix, es el mismo). Nombre: brew-atlas-app. El flag --template react-router es equivalente a --template remix — desde finales de 2025, el template de Remix se renombró a React Router v7. El alias remix sigue funcionando y apunta al mismo template.

Una vez generado, el servidor de desarrollo se levanta desde ~/proyectos/shopify/brew-atlas/brew-atlas-app/:

shopify app dev

Estructura del proyecto generado

El template produce esta estructura (simplificada a los archivos relevantes):

// ~/proyectos/shopify/brew-atlas/brew-atlas-app/ (directorio raiz del app generado por CLI)
brew-atlas-app/
├── shopify.app.toml          ← config del app, scopes, webhooks
├── shopify.server.ts         ← integración shopify-app-remix
├── prisma/
│   └── schema.prisma         ← esquema SQLite por defecto
├── app/
│   ├── shopify.config.ts     ← config de la sesión y OAuth
│   ├── db.server.ts          ← cliente Prisma
│   └── routes/
│       ├── app.tsx           ← layout raíz con providers de Polaris y App Bridge
│       ├── app._index.tsx    ← ruta principal del dashboard
│       └── webhooks.tsx      ← handler de webhooks
└── extensions/               ← aquí van las extensiones del app

La separación entre shopify.server.ts y app/shopify.config.ts es importante: shopify.server.ts es la instancia del SDK de Shopify para el servidor, configurada con las credenciales de la app. app/shopify.config.ts consume esa instancia y la exporta con los helpers de autenticación que usan tus loaders y actions.

shopify.app.toml — configuración central

El archivo shopify.app.toml es donde declaras los scopes, los webhooks, las URLs del app, y las extensiones que va a incluir el deploy:

# ~/proyectos/shopify/brew-atlas/brew-atlas-app/shopify.app.toml
name = "Brew Atlas"
client_id = "TU_CLIENT_ID"
application_url = "https://tu-servidor.com"
embedded = true
 
[access_scopes]
scopes = "read_products,write_products,read_orders,read_customers,write_customers"
 
[auth]
redirect_urls = [
  "https://tu-servidor.com/auth/callback",
  "https://tu-servidor.com/auth/shopify/callback"
]
 
[[webhooks.subscriptions]]
topics = ["app/uninstalled"]
uri = "/webhooks"
 
[[webhooks.subscriptions]]
topics = ["orders/create"]
uri = "/webhooks"

La clave embedded = true le indica a Shopify que esta app debe renderizarse dentro del Admin. Sin esa declaración, Shopify la trata como una app standalone y no inyecta el runtime de App Bridge.

Session tokens: autenticación sin redirecciones

El mecanismo de autenticación de las apps embebidas merece explicación detallada porque es diferente al flujo OAuth tradicional.

Cuando el comerciante navega a tu app dentro del Admin, App Bridge inyecta automáticamente un session token — un JWT firmado por Shopify — en cada request que hace tu app al servidor. Ese JWT contiene el identificador del shop y expira en un minuto (por diseño, para forzar rotación frecuente).

Tu servidor recibe ese JWT, lo verifica contra el client secret de tu app, y lo intercambia por el access token de larga duración del comerciante (stored en tu DB) mediante el proceso llamado Token Exchange. El acceso token es el que realmente usas para llamar al Admin GraphQL API.

El template del CLI encapsula todo esto en el helper authenticate.admin(request).

Editá ~/proyectos/shopify/brew-atlas/brew-atlas-app/app/routes/app._index.tsx:

// ~/proyectos/shopify/brew-atlas/brew-atlas-app/app/routes/app._index.tsx
import { json } from '@remix-run/node';
import { authenticate } from '~/shopify.server';
 
export async function loader({ request }: { request: Request }) {
  const { admin, session } = await authenticate.admin(request);
 
  // 'admin' es un cliente de Admin API ya autenticado con el token del comerciante
  const response = await admin.graphql(`#graphql
    query {
      shop {
        name
        myshopifyDomain
        plan { displayName }
      }
    }
  `);
 
  const { data } = await response.json();
  return json({ shop: data.shop });
}

Si el JWT es inválido o expiró, authenticate.admin redirige automáticamente al flujo de re-autenticación. No tienes que manejar ese caso manualmente.

Polaris: el sistema de diseño obligatorio

Polaris 13.x es el sistema de diseño de Shopify. Para apps que quieran la certificación “Built for Shopify”, usar Polaris en todas las superficies del Admin no es opcional — es un requisito. Incluso sin la certificación, usarlo reduce la fricción para el comerciante: tu app tiene el mismo lenguaje visual que el resto del Admin.

Los componentes más usados en apps embebidas.

Ejemplo de pantalla principal en ~/proyectos/shopify/brew-atlas/brew-atlas-app/app/routes/app._index.tsx:

// ~/proyectos/shopify/brew-atlas/brew-atlas-app/app/routes/app._index.tsx
import {
  Page,
  Layout,
  Card,
  DataTable,
  Badge,
  Button,
  TextField,
  Select,
} from '@shopify/polaris';
 
export default function Index() {
  const { shop } = useLoaderData<typeof loader>();
 
  return (
    <Page
      title="Brew Atlas Admin"
      subtitle={`Tienda: ${shop.name}`}
      primaryAction={<Button variant="primary">Nueva suscripción</Button>}
    >
      <Layout>
        <Layout.Section>
          <Card>
            <DataTable
              columnContentTypes={['text', 'text', 'numeric', 'text']}
              headings={['Tier', 'Frecuencia', 'Precio', 'Estado']}
              rows={[
                ['Monthly 1 bag', 'Mensual', '$15.00', <Badge tone="success">Activo</Badge>],
                ['Monthly 2 bags', 'Mensual', '$28.00', <Badge tone="success">Activo</Badge>],
                ['Quarterly sampler', 'Trimestral', '$42.00', <Badge>Borrador</Badge>],
              ]}
            />
          </Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

La jerarquía de Polaris que usarás en el 95% de las pantallas: Page → Layout → Layout.Section → Card. Page maneja el título, las acciones primarias y secundarias, y el breadcrumb. Card es el contenedor de contenido. DataTable para tablas. Form, TextField, Select para formularios.

App Bridge: acciones del Admin

App Bridge 3.x usa web components — custom elements del navegador cargados desde la CDN de Shopify. No necesitas instalar ningún paquete npm: el script de App Bridge lo inyecta el template de React Router v7 automáticamente cuando la app está embebida.

Los web components de App Bridge que más usarás.

Editá el layout raíz en ~/proyectos/shopify/brew-atlas/brew-atlas-app/app/routes/app.tsx:

// ~/proyectos/shopify/brew-atlas/brew-atlas-app/app/routes/app.tsx (layout raiz)
// App Bridge web components — se renderizan en el cliente, fuera del SSR
export default function AppLayout() {
  return (
    <>
      {/* Barra de título del Admin con acciones */}
      <ui-title-bar title="Brew Atlas">
        <button variant="primary" onClick={() => openModal()}>
          Nueva suscripción
        </button>
      </ui-title-bar>
 
      {/* Modal nativo del Admin */}
      <ui-modal id="new-subscription-modal">
        <ui-title-bar title="Crear tier de suscripción"></ui-title-bar>
        <p>Contenido del modal aquí</p>
        <button slot="primary-action" variant="primary">
          Guardar
        </button>
        <button slot="secondary-action">Cancelar</button>
      </ui-modal>
 
      <Outlet />
    </>
  );
}

Los custom elements como <ui-title-bar>, <ui-modal>, <ui-nav-menu> se comunican con el shell del Admin directamente. No son divs disfrazados — el Admin los procesa y renderiza en sus propias regiones (la barra superior, los modales del sistema, la navegación lateral). Esto es lo que hace que la app se sienta nativa.

Para mostrar un toast (notificación temporal):

// Desde cualquier componente cliente
import { useAppBridge } from '@shopify/app-bridge-react';
// O directamente con el web component:
const shopify = window.shopify; // inyectado por el script de App Bridge
shopify.toast.show('Suscripción guardada', { duration: 3000 });

Scopes y permisos de la app

Los scopes que tu app puede ejercer se declaran en shopify.app.toml bajo [access_scopes]. El comerciante los aprueba durante la instalación — ve una pantalla que lista exactamente qué puede hacer tu app. Si pides un scope y después intentas usar otro no declarado, el Admin API rechaza la operación.

Reglas prácticas sobre scopes:

• Pide solo los scopes que realmente usas — cada scope adicional reduce la tasa de conversión en la instalación
• write_X incluye read_X implícitamente
• Algunos recursos tienen scopes más granulares desde 2024 — consulta la doc de cada recurso para el scope exacto
• Si necesitas un scope adicional después del despliegue, el comerciante tiene que re-aceptar la instalación

Puentes mentales

Estado 2026

Lo relevante al 2026:

• React Router v7 es el framework recomendado para apps de Shopify. El template anterior era Remix (que se convirtió en React Router v7 en 2025). Si ves tutoriales con @remix-run/node o @remix-run/react, siguen siendo válidos — son los mismos paquetes bajo un nombre diferente a partir de cierta versión.
• Token Exchange reemplazó al flujo de OAuth de redirección para apps embebidas. No necesitas redirigir al comerciante fuera del Admin para autenticar — el session token JWT lo hace en segundo plano.
• Polaris 13.x: los componentes LegacyCard, LegacyStack, y otros marcados como “legacy” en v12 están eliminados en v13. Si migras una app antigua, revisa el migration guide de Polaris.
• App Bridge 4.x (web components) es el modelo actual. El wrapper de React @shopify/app-bridge-react sigue disponible como capa de compatibilidad, pero la API canónica son los web components.

Proyecto · Brew Atlas

npm init @shopify/app@latest

shopify app dev

Errores comunes

Checklist senior

Quiz

Siguiente

Con la capa de UI del Admin cubierta, el siguiente bloque entra en el territorio del backend distribuido de Shopify: las Shopify Functions. Son módulos de WebAssembly que tu app despliega en la infraestructura de Shopify para extender la lógica de negocio del checkout — descuentos, validaciones, transformaciones de carrito — sin gestionar ningún servidor.