ابنِ من القالب

قالب حسنات نقطة البداية المقترحة للتطبيقات الجديدة. هو مستودع عام برخصة MIT، ومعدّ للعربية أولًا ولـ Cloudflare.

ما في القالب

Astro 5 مع العرض على الخادم، وReact 19 للأجزاء التفاعلية.
Tailwind CSS v4، وTypeScript بالوضع الصارم.
العربية افتراضيًا من اليمين إلى اليسار، والإنجليزية.
ربط جاهز مع تسجيل الدخول المشترك.
مساعدات لقاعدة بيانات Cloudflare D1، وإعداد للنشر على Cloudflare Pages.
Biome للتنسيق والفحص، وzod للتحقق من المدخلات، وlucide-react للأيقونات.
أربع مهارات لوكلاء البرمجة في .github/skills/. نسخها أقدم من حزمة المهارات، فاعتمد نسخ الحزمة.

المتطلبات

git، وNode.js 20 أو أحدث، وnpm. يعتمد القالب على npm وملف package-lock.json، فلا تغيّر مدير الحزم.

التشغيل لأول مرة

أنشئ نسختك. اضغط Use this template في صفحة القالب على GitHub لتنشئ مستودعك، أو انسخه مباشرة:
نافذة طرفيّة
```
git clone --depth 1 https://github.com/hasanat-dev/starter.git my-app
cd my-app
```
ثبّت الاعتماديات، وانسخ ملف البيئة:
نافذة طرفيّة
```
npm install
cp .env.example .env
```
شغّل خادم التطوير:
نافذة طرفيّة
```
npm run dev
```
افتح الرابط الذي يطبعه Astro، وهو عادة http://localhost:4321. يحوّلك الجذر إلى /ar/. إن كان المنفذ مشغولًا فاستخدم الرابط الذي يختاره Astro، ولا توقف عملية أخرى.
تأكّد من البناء قبل أي تعديل:
نافذة طرفيّة
```
npm run check
npm run build
```

نقطة النجاح الأولى صفحة حقيقية تعمل على جهازك. تسجيل الدخول وقاعدة البيانات والنشر خطوات لاحقة واختيارية.

مشكلات معروفة في القالب

جرّبنا القالب كما هو في 13 أكتوبر 2026: التثبيت والبناء وخادم التطوير تعمل، لكن أمرين يفشلان.

npm run check يعرض خطأً واحدًا: Cannot find name 'D1Result' في src/lib/db.ts. أضف هذا السطر إلى src/env.d.ts بجانب تعريف D1Database:
```
type D1Result = import("@cloudflare/workers-types").D1Result;
```
npm run lint يتوقّف لأن biome.json مكتوب لإصدار Biome 1، والقالب يثبّت Biome 2. الأمر npx biome migrate --write يحدّث الإعداد، لكن بعض القواعد تبقى تشتكي من ملفات Astro ومن صيغ Tailwind. اعتمد على npm run check وnpm run build إلى أن يُصلَح القالب.

ملف البيئة

في .env.example متغيّران فقط: PUBLIC_SITE_URL وPUBLIC_APP_NAME. تسجيل الدخول المشترك لا يحتاج أي سرّ.
في الملف سطران معلّقان HASANAT_CLIENT_ID وHASANAT_CLIENT_SECRET لتدفق OAuth للتطبيقات الخارجية. هذا التدفق غير موجود اليوم، فاتركهما كما هما. انظر تسجيل الدخول.
لا تضع أسرارًا في المستودع، ولا ترسلها في محادثة أو طلب.

بنية المشروع

src/
├── middleware.ts      يقرأ جلسة تسجيل الدخول
├── lib/
│   ├── auth.ts        روابط الدخول والخروج وحماية الصفحات
│   └── db.ts          مساعدات D1
├── layouts/
│   └── Layout.astro   يضبط lang وdir
├── pages/
│   ├── index.astro    يحوّل إلى /ar/
│   ├── ar/            الصفحات العربية
│   ├── en/            الصفحات الإنجليزية
│   └── api/health.ts
├── i18n/              ar.json وen.json وutils.ts
└── styles/global.css  ألوان Tailwind والخطوط
schema.sql             مخطّط قاعدة البيانات
wrangler.toml          إعداد Cloudflare
.env.example
.github/skills/        مهارات وكلاء البرمجة
AGENTS.md              تعليمات وكلاء البرمجة
DATA_POLICY.md         سياسة البيانات للبنّائين

الأوامر

الأمر	ماذا يفعل
`npm run dev`	يشغّل خادم التطوير على `localhost:4321`
`npm run build`	يبني نسخة الإنتاج
`npm run preview`	يعاين البناء على جهازك
`npm run lint`	يفحص الكود بـ Biome
`npm run check`	يفحص TypeScript وAstro
`npm run db:migrate:local`	يطبّق `schema.sql` على قاعدة D1 المحلية
`npm run db:migrate:prod`	يطبّقه على قاعدة الإنتاج

قبل أوامر قاعدة البيانات، ضع اسم قاعدتك مكان YOUR_DB_NAME في package.json.

اصطلاحات القالب

من ملف AGENTS.md في القالب:

استورد بالمسار المختصر @/.
استخدم خصائص Tailwind المنطقية مثل ms-* وpe-* بدل ml-* وpr-*.
أضف كل نص يظهر للمستخدم إلى ar.json وen.json معًا، ولا تكتبه مباشرة في الصفحة.
Biome للتنسيق لا Prettier، وzod للتحقق من المدخلات، وlucide-react للأيقونات.
لا تضف Firebase أو مزوّد دخول آخر: استخدم auth.hasanat.dev وD1.

بعد أن تعمل الصفحة الأولى

شكّل النسخة الأولى حول نتيجة واحدة مفيدة، كما في المواصفات إن كان المشروع من مشاريع حسنات.
حين تحتاج تسجيل الدخول أو قاعدة بيانات أو نطاقًا، اقرأ الخدمات المشتركة.
يشير ملف README في القالب إلى صفحة إرسال قديمة على hasanat.dev لم تعد مسار العمل. اطلب النطاق والإدراج من لوحة المنصة.