Skip to content
Dukkan DevelopersDocs
العربيةSign in

Build an app with the SDK in 5 minutes

From an empty folder to a signed webhook received on your machine, with the CLI, the Nuxt module and a sandbox store.

Updated 9 Sept 20262 min read
On this page

This page is for developers who want the fastest correct path to a running Dukkan app. By the end you have a scaffolded Nuxt app, a draft version registered from its dukkan.app.toml, a public URL, an install on your sandbox store, and a signed order.created delivery verified by your own code.

You need Node.js 18.17 or newer, a developer account with a sandbox store (Sandbox stores), and cloudflared on your PATH for the public URL. Without cloudflared, pass --tunnel-url with any HTTPS tunnel you already run.

1. Scaffold#

Shell
npx @dukkan.one/cli app init my-app
cd my-app && npm install && cp .env.example .env

app init asks for a name, a template and the scopes, then writes a Nuxt 4 project with @dukkan.one/nuxt, a dukkan.app.toml, and an .env.example. The nuxt-minimal template keeps installs in memory (right for a first run); nuxt-postgres ships sealed tokens and a durable inbox for a real deployment.

2. Sign in#

Shell
npx @dukkan.one/cli login

A device-flow sign-in binds the CLI to one sandbox store. It can never reach a real store, and app commands only touch your own team's apps.

3. Register the draft#

Shell
npx @dukkan.one/cli app config push

The first push creates your app's draft version from the file and prints the portal page. Open it once: copy the client id into NUXT_DUKKAN_CLIENT_ID and the client secret into NUXT_DUKKAN_CLIENT_SECRET in .env, and put any 32 random characters into NUXT_DUKKAN_SESSION_SECRET. Every key of the file is explained in The dukkan.app.toml file.

4. Run#

Shell
npx @dukkan.one/cli app dev

The CLI starts the app, opens a tunnel, registers a development session with the tunnel's callback URL, and prints an install link for your sandbox:

Text
Starting app: npx nuxi dev --port 3000
Opening tunnel…

✓ my-app is running
  App:          http://localhost:3000
  Public URL:   https://lively-otter-1234.trycloudflare.com
  Webhook:      https://lively-otter-1234.trycloudflare.com/dukkan/webhooks
  Sandbox:      Sham Perfumes (sham-perfumes)
  Install:      http://localhost:3000/dukkan/install?store=sham-perfumes&install_token=REDACTED
  Session ends: 2026-09-09T22:10:00.000Z

Waiting for events. Ctrl+C to stop.

A development session lives at most 8 hours and only ever points at your sandbox; nothing about the tunnel is written into the version merchants will install. Open http://localhost:3000 to see the setup checklist turn green step by step.

5. Install on the sandbox#

Open the install link. The platform shows the consent screen for the scopes in your file; approve it and the app lands you on its "Connected" screen. Behind that click the module exchanged the code, saved the tokens under the platform's install_id and store_id, and registered the webhook subscription.

6. Receive a signed event#

In a second terminal:

Shell
npx @dukkan.one/cli app webhook trigger order.created

The platform builds a sample from your sandbox's own seeded data, signs it with the install's real secret and delivers it through the real pipeline. Both terminals show it:

Text
✓ order.created queued as event 9f3a1c2b… (1 delivery). Watch it arrive in `dukkan app dev`.
  → https://lively-otter-1234.trycloudflare.com/dukkan/webhooks (delivery 4c1d9e0a…)
Text
✓ 14:05:12 order.created                9f3a1c2b  200 test

The test marker means the envelope carried test: true; production installs never receive one. Your handler in server/dukkan.ts ran with a typed event.data.

Next steps#

  • The Nuxt module: what was mounted and the contract your server/dukkan.ts fulfils.
  • Webhooks: the envelope, retries and the idempotent handler pattern the receiver implements.
  • Publish your app when a real merchant should install it.