Tu Primer Plugin

Un tutorial completo de principio a fin — desde el scaffolding hasta un plugin funcionando con datos reales de la tienda en 15 minutos.

Este tutorial construye un plugin funcional paso a paso. Al final tendrás un plugin con dos páginas, contexto real de la tienda, una acción toast y un despliegue completo al Developer Portal.

Paso 1: Crear el Plugin

Ejecuta el scaffolder:

npx create-whatalo-plugin

Las preguntas:

? Nombre del plugin: Mi Primer Plugin
? Plantilla: React + Vite
? ¿Crear nuevo o vincular existente? Crear nuevo

El scaffolder crea el directorio del proyecto, instala dependencias y registra una nueva entrada de plugin en el Developer Portal.

Paso 2: Explorar la Estructura del Proyecto

mi-primer-plugin/
├── whatalo.app.ts          ← Manifiesto del plugin — páginas, permisos, webhooks
├── whatalo.app.toml        ← Config del proyecto — slug, comandos de build, puerto
├── package.json
├── vite.config.ts
├── src/
│   ├── app.tsx             ← Componente principal — router de páginas
│   ├── main.tsx            ← Punto de entrada de React
│   ├── pages/
│   │   └── settings.tsx    ← Componente de la página Settings
│   ├── webhooks/
│   │   └── verify.ts       ← Helper de firma de webhook
│   └── components/
│       └── whatalo-ui/     ← Componentes UI preconstruidos
└── .env.example

Dos archivos controlan todo:

whatalo.app.ts define la identidad, páginas y permisos de tu plugin
whatalo.app.toml le dice al CLI cómo construir y ejecutarlo

Paso 3: Revisar el Manifiesto

Abre whatalo.app.ts. Esto es lo que genera el scaffolder:

import { defineApp } from "@whatalo/plugin-sdk/manifest";

export default defineApp({
  id: "mi-primer-plugin",
  name: "Mi Primer Plugin",
  description: "Starter de plugin generado con create-whatalo-plugin.",
  version: "0.1.0",
  author: {
    name: "Tu Equipo",
    email: "[email protected]",
  },
  permissions: ["read:store"],
  appUrl: "https://tu-url-tunel.com",
  webhookUrl: "https://tu-url-tunel.com/webhooks/whatalo",
  pricing: "free",
  category: "developer",
  adminUI: {
    pages: [
      {
        path: "dashboard",
        title: "Dashboard",
        icon: "puzzle",
        position: "sidebar",
      },
      {
        path: "settings",
        title: "Settings",
        navigationLabel: "Configuración",
        icon: "settings",
        position: "sidebar",
      },
    ],
  },
});

Puntos clave:

id — identificador único del plugin. Inmutable después del registro.
permissions — a qué datos de la tienda puede acceder tu plugin. Comienza con solo read:store.
adminUI.pages — cada entrada crea un elemento en la barra lateral. La primera página es la predeterminada.
appUrl y webhookUrl — el CLI los sobreescribe con la URL del túnel durante whatalo dev.

Paso 4: Revisar la Config TOML

Abre whatalo.app.toml:

# whatalo.app.toml — Generado por `whatalo init`

[plugin]
name = "Mi Primer Plugin"
plugin_id = "plg_abc123..."
slug = "mi-primer-plugin"

[build]
dev_command = "pnpm dev"
build_command = "pnpm build"
output_dir = "dist"

[dev]
port = 5173

plugin_id se establece automáticamente durante el scaffolding — vincula este proyecto con la entrada del plugin en el Developer Portal.

Paso 5: Autenticarse

cd mi-primer-plugin
whatalo login

Tu navegador se abre. Confirma el código de dispositivo mostrado en la terminal. Al tener éxito:

✓ Logged in as [email protected]

Paso 6: Iniciar la Sesión de Desarrollo

whatalo dev

El CLI inicia tu servidor Vite, crea un túnel cloudflared y registra una sesión temporal en la barra lateral del admin. Observa una salida como:

✓ Authenticated as [email protected]
✓ Manifest loaded (2 admin pages)
✓ Local server running at http://localhost:5173
✓ Tunnel active at https://abc123.trycloudflare.com
✓ Development session active

  Plugin:  Mi Primer Plugin
  Store:   Mi Tienda Demo
  Local:   http://localhost:5173
  Tunnel:  https://abc123.trycloudflare.com

  Preview: https://admin.whatalo.com/store/abc/integrations/mi-primer-plugin

  Admin pages:
    › Dashboard  → .../integrations/mi-primer-plugin
    › Settings   → .../integrations/mi-primer-plugin/settings

  Press p to open preview in browser
  Press r to restart server
  Press q to quit

Presiona p — el admin se abre con tu plugin en la barra lateral.

Paso 7: Entender el Componente App

Abre src/app.tsx. Este es el router principal:

import { useWhataloContext } from "@whatalo/plugin-sdk/bridge";
import { useThemeSync, useAutoResize } from "./components/whatalo-ui";
import { SettingsPage } from "./pages/settings";

export function App() {
  // Sincroniza el tema oscuro/claro del admin con el document root
  useThemeSync();
  // Reporta la altura del contenido al host para que el admin gestione el scroll
  useAutoResize();

  const context = useWhataloContext();

  // Espera a que se complete el handshake del App Bridge
  if (!context.isReady) {
    return null;
  }

  // Ruta a la página correcta basada en lo que nos dice el admin
  switch (context.currentPage) {
    case "settings":
      return <SettingsPage />;
    case "dashboard":
    default:
      return <DashboardPage />;
  }
}

useWhataloContext() te da el objeto de contexto completo incluyendo currentPage, storeName, user y theme. El flag isReady pasa a true una vez que el handshake del App Bridge se completa — siempre protege tu renderizado con esto.

Paso 8: Mostrar Datos Reales de la Tienda

La página Dashboard en la plantilla ya muestra el contexto de la tienda. Aquí está la parte relevante:

function DashboardPage() {
  const context = useWhataloContext();

  return (
    <Page>
      <PageHeader title="Mi Plugin" subtitle="Starter listo para desarrollo" />
      <Layout>
        <Layout.Section>
          <Card>
            <BlockStack gap="300">
              <Text as="h2" variant="headingMd">Contexto de la Tienda</Text>
              <Box padding="300" background="surface-active" borderRadius="200">
                <BlockStack gap="200">
                  <InlineStack align="space-between">
                    <Text variant="bodySm" color="subdued">Tienda</Text>
                    <Text variant="bodySm" fontWeight="semibold">{context.storeName}</Text>
                  </InlineStack>
                  <InlineStack align="space-between">
                    <Text variant="bodySm" color="subdued">Usuario</Text>
                    <Text variant="bodySm" fontWeight="semibold">{context.user.email}</Text>
                  </InlineStack>
                  <InlineStack align="space-between">
                    <Text variant="bodySm" color="subdued">Tema</Text>
                    <Badge tone="info">{context.theme}</Badge>
                  </InlineStack>
                </BlockStack>
              </Box>
            </BlockStack>
          </Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

Estos datos vienen directamente del admin sin necesidad de llamada a API — se envían a tu plugin vía App Bridge tan pronto como el handshake se completa.

Paso 9: Disparar un Toast desde tu Plugin

El hook useAppBridge() combina contexto y acciones en una sola API. Agrega un toast al Dashboard:

import { useAppBridge } from "@whatalo/plugin-sdk/bridge";

function DashboardPage() {
  const bridge = useAppBridge();

  async function handleSave() {
    // ... tu lógica de guardado ...
    await bridge.toast.show("¡Configuración guardada!", { variant: "success" });
  }

  return (
    <Page>
      <PageHeader title="Mi Plugin" />
      <Layout>
        <Layout.Section>
          <Card>
            <BlockStack gap="300">
              <Text variant="bodyMd">Tienda: {bridge.storeName}</Text>
              <Button variant="primary" onClick={handleSave}>
                Guardar
              </Button>
            </BlockStack>
          </Card>
        </Layout.Section>
      </Layout>
    </Page>
  );
}

Haz clic en el botón en el admin — aparece un toast de éxito en la parte superior de la pantalla.

Paso 10: Agregar Navegación entre Páginas

Las páginas se enrutan vía currentPage, que coincide con el path en tu manifiesto. La página Settings ya está conectada. Navega entre páginas usando la barra lateral — o activa la navegación desde tu plugin:

const bridge = useAppBridge();

// Navegar a la página de settings
bridge.navigate(`/store/${bridge.storeId}/integrations/mi-primer-plugin/settings`);

Paso 11: Editar el Manifiesto en Vivo

Agrega una tercera página a whatalo.app.ts mientras whatalo dev está corriendo:

adminUI: {
  pages: [
    { path: "dashboard", title: "Dashboard", icon: "puzzle", position: "sidebar" },
    { path: "settings", title: "Settings", icon: "settings", position: "sidebar" },
    { path: "reports", title: "Reportes", icon: "chart-bar", position: "sidebar" },
  ],
},

Guarda el archivo. El CLI detecta el cambio y sincroniza el manifiesto con el admin en un segundo. Recarga el admin — ahora ves tres elementos en la barra lateral.

Agrega el manejador de ruta en src/app.tsx:

switch (context.currentPage) {
  case "settings":
    return <SettingsPage />;
  case "reports":
    return <ReportsPage />;
  case "dashboard":
  default:
    return <DashboardPage />;
}

Paso 12: Solicitar Más Permisos

Si tu plugin necesita datos de pedidos, actualiza permissions en el manifiesto:

permissions: ["read:store", "read:orders", "read:customers"],

Los permisos se revisan cuando un dueño de tienda instala tu plugin. Solo solicita lo que realmente usas.

Paso 13: Validar Antes de Desplegar

whatalo validate

El validador verifica:

whatalo.app.toml está presente y es válido
El manifiesto whatalo.app.ts está presente
Dependencias requeridas instaladas (@whatalo/plugin-sdk, react, vite)
Sin secretos hardcodeados en archivos fuente
.gitignore cubre .env, .whatalo/, node_modules/
TypeScript compila sin errores
El puerto de desarrollo está disponible

Una salida limpia significa que estás listo para desplegar:

  Whatalo Plugin Validator
  ========================

  Config
  ✓ whatalo.app.toml found and valid

  Manifest
  ✓ whatalo.app.ts manifest found

  Dependencies
  ✓ @whatalo/plugin-sdk installed (^0.0.1)
  ✓ react installed (^19.0.0)
  ✓ vite installed (^6.0.0)

  Security
  ✓ No secrets found in source files
  ✓ .gitignore covers all required entries

  TypeScript
  ✓ TypeScript compilation passes

  Port
  ✓ Port 5173 is available

✓ All 9 checks passed — ready to submit!

Paso 14: Desplegar

whatalo deploy --force

El CLI construye tu proyecto, lee la versión de package.json y sube el manifiesto al Developer Portal:

✓ Authenticated as [email protected]
✓ Config valid (whatalo.app.toml)
✓ Build succeeded

  Deploy Complete
  ───────────────
  Plugin     Mi Primer Plugin
  Version    0.1.0
  Status     draft

Paso 15: Enviar para Revisión

Después de desplegar, abre el dashboard del Developer Portal y navega a tu plugin. Desde la página de detalle del plugin, haz clic en Enviar para Revisión. El equipo de Whatalo revisa tu plugin y lo aprueba o lo devuelve con comentarios.

Una vez aprobado, tu plugin aparece listado en el marketplace.

Lo Que Construiste

Un plugin React + Vite con dos páginas (Dashboard + Settings)
Contexto real de la tienda mostrado desde el App Bridge
Una acción toast disparada desde tu plugin
Una sesión dev en vivo con un túnel cloudflared
Validado y desplegado al Developer Portal

Próximos Pasos

Referencia App Bridge — todos los campos de contexto, acciones y API de facturación
Referencia CLI — documentación completa de los 14 comandos
Configuración — campos del manifiesto, alcances de permisos, opciones TOML
Webhooks — recibe eventos en tiempo real de la tienda
Facturación — cobra por tu plugin con planes de suscripción

On this page