Quick Start

Prerequisites

Node.js 18 or higher
pnpm (recommended), npm, or yarn
A Whatalo developer account — sign up at the Developer Portal
A development store (create one in the Developer Portal, up to 3 allowed)

Step 1: Scaffold Your Plugin

npx create-whatalo-plugin

The scaffolder asks for a plugin name and creates a React + Vite project. No global install needed.

Step 2: Authenticate

cd my-plugin
whatalo login

Your browser opens automatically. Confirm the device code shown in the terminal. Once confirmed, the CLI stores an access token locally.

Step 3: Start the Dev Server

whatalo dev

The CLI does three things simultaneously:

Starts your local app server on port 5173
Creates a cloudflared tunnel (downloaded automatically on first use)
Registers a temporary dev session in the admin sidebar

You'll see output like this:

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

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

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

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

Step 4: Open the Admin

Press p or copy the preview URL. Your plugin appears in the admin sidebar under Integrations. Both the Dashboard and Settings pages defined in the manifest are already linked as sub-items.

What Was Scaffolded

my-plugin/
├── whatalo.app.ts          ← Plugin manifest (defineApp)
├── whatalo.app.toml        ← Project config (slug, build commands, port)
├── package.json
├── vite.config.ts
├── server/
│   ├── auth.ts              ← Session-token verification for backend routes
│   ├── env.ts               ← Server environment parsing
│   └── index.ts             ← Backend routes + webhook receiver
├── src/
│   ├── app.tsx             ← Main component with page router (switch on currentPage)
│   ├── lib/plugin-api.ts   ← Frontend helper for same-origin /api calls
│   ├── main.tsx            ← React entry point
│   ├── pages/
│   │   └── settings.tsx    ← Settings page component
│   ├── webhooks/
│   │   └── verify.ts       ← Webhook signature verification helper
│   └── components/
│       └── whatalo-ui/     ← Pre-built UI components (Page, Card, Button, etc.)
└── .env.example

The generated starter keeps the iframe frontend, /api/*, and /webhooks/whatalo on the same tunneled origin during development.

Example: Update an Order with WhataloClient

If your plugin needs to move orders through the fulfillment flow, declare write:orders in whatalo.app.ts:

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

export default defineApp({
  // ...other fields
  permissions: ["read:orders", "write:orders"],
});

Then call WhataloClient from your plugin backend:

import { WhataloClient } from "@whatalo/plugin-sdk/client";

const client = new WhataloClient({ apiKey: process.env.WHATALO_API_KEY! });

const response = await client.orders.updateStatus("819365047283", {
  status: "confirmed",
});

console.log(response.data.status);

Use status as the public field name when updating or reading orders through the SDK.

What Happens When You Change the Manifest

Edit whatalo.app.ts while whatalo dev is running. The CLI detects the change, reloads the manifest, and syncs the updated page list to the admin sidebar — no restart needed.

Next Steps

Build Your First Plugin — full end-to-end tutorial
Plugin Architecture — understand the iframe and App Bridge model
CLI Reference — all 14 commands
App Bridge — how to use context and actions

On this page