ابنِ تطبيقاً بالحزمة خلال 5 دقائق

هذه الصفحة للمطوّرين الذين يريدون أسرع طريق صحيح إلى تطبيق دكان يعمل. في نهايتها يكون لديك تطبيق Nuxt مولَّد، ومسودة إصدار مسجّلة من ملفه dukkan.app.toml، ورابط عام، وتثبيت على متجرك التجريبي، وتسليم order.created موقّع تحقّقت منه شيفرتك أنت.

تحتاج Node.js 18.17 أو أحدث، وحساب مطوّر بمتجر تجريبي (المتاجر التجريبية)، وcloudflared على مسارك للرابط العام. من دون cloudflared مرّر --tunnel-url مع أي نفق HTTPS تشغّله أصلاً.

١. أنشئ الهيكل#

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

يسألك app init عن اسم وقالب ونطاقات، ثم يكتب مشروع Nuxt 4 مع @dukkan.one/nuxt وملف dukkan.app.toml وملف .env.example. يحفظ قالب nuxt-minimal التثبيتات في الذاكرة (مناسب لأول تشغيل)؛ ويأتي nuxt-postgres برموز مختومة وصندوق وارد دائم لنشر حقيقي.

٢. سجّل الدخول#

npx @dukkan.one/cli login

يربط تسجيل الدخول بتدفق رمز الجهاز الأداةَ بمتجر تجريبي واحد. لا تستطيع الوصول إلى متجر حقيقي أبداً، ولا تلمس أوامر app سوى تطبيقات فريقك.

٣. سجّل المسودة#

npx @dukkan.one/cli app config push

ينشئ الدفع الأول مسودة إصدار تطبيقك من الملف ويطبع صفحة البوابة. افتحها مرة واحدة: انسخ معرّف العميل إلى NUXT_DUKKAN_CLIENT_ID والمفتاح السري إلى NUXT_DUKKAN_CLIENT_SECRET في .env، وضع أي 32 حرفاً عشوائياً في NUXT_DUKKAN_SESSION_SECRET. كل مفتاح في الملف مشروح في ملف dukkan.app.toml.

٤. شغّل#

npx @dukkan.one/cli app dev

تشغّل الأداة التطبيق، وتفتح نفقاً، وتسجّل جلسة تطوير برابط إعادة التوجيه الخاص بالنفق، وتطبع رابط تثبيت لمتجرك التجريبي:

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.

تعيش جلسة التطوير 8 ساعات على الأكثر ولا تشير إلا إلى متجرك التجريبي؛ لا يُكتب شيء عن النفق في الإصدار الذي سيثبّته التجار. افتح http://localhost:3000 لترى قائمة الإعداد تخضرّ خطوة بخطوة.

٥. ثبّت على المتجر التجريبي#

افتح رابط التثبيت. تعرض المنصّة شاشة الموافقة لنطاقات ملفك؛ وافق فيوصلك التطبيق إلى شاشة «متصل». خلف تلك النقرة بدّلت الوحدة الكود، وحفظت الرموز تحت install_id وstore_id من المنصّة، وسجّلت اشتراك Webhooks.

٦. استقبل حدثاً موقّعاً#

في طرفية ثانية:

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

تبني المنصّة عيّنة من بيانات متجرك التجريبي المزروعة، وتوقّعها بسر التثبيت الحقيقي، وتسلّمها عبر خط الأنابيب الحقيقي. تعرضها الطرفيتان:

✓ 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…)

✓ 14:05:12 order.created                9f3a1c2b  200 test

تعني علامة test أن الغلاف حمل test: true؛ لا تستقبل تثبيتات الإنتاج واحداً أبداً. عمل معالجك في server/dukkan.ts مع event.data منمّط.

الخطوات التالية#

• وحدة Nuxt: ما رُكِّب والعقد الذي يفي به server/dukkan.ts لديك.
• Webhooks: الغلاف وإعادة المحاولة ونمط المعالج الآمن للتكرار الذي ينفّذه المستقبِل.
• انشر تطبيقك عندما يجب أن يثبّته تاجر حقيقي.