دليل البُناة

كل ما تحتاجه للبناء على منصة حسنات — ماذا تحصل عليه، كيف تبدأ، الموارد، والتوثيق التقني

ماذا تحصل عليه

بنية تحتية جاهزة ومجانية حتى تركّز على بناء فكرتك بدل إعداد الخوادم.

استضافة مجانية

Cloudflare Pages + نطاق .hasanat.dev

تسجيل دخول موحد

auth.hasanat.dev يعمل عبر كل التطبيقات

قاعدة بيانات

Cloudflare D1 — SQL خفيف وسريع

بريد إلكتروني

Resend مع نطاق hasanat.dev مفعّل

مجتمع ومختبرون

ملاحظات حقيقية ومتطوعون للتجربة

إطلاق وتوزيع

إعلان في المنصة والنشرة البريدية

كيف تبدأ

1

اختر فكرة

تصفح الأفكار المطروحة أو اقترح فكرتك الخاصة

2

ابدأ البناء

انسخ قالب البداية من github.com/hasanat-dev/starter

3

أرسل تطبيقك

أرسل تطبيقك عبر صفحة الإرسال واحصل على نطاق فرعي

4

أطلق للمجتمع

نعلن عن تطبيقك في المنصة والنشرة البريدية

من الفكرة إلى صفحة تعمل خلال دقائق

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

1

راجع المصدر

اقرأ تعليمات المهارة قبل منحها للوكيل.

2

ثبّت المهارة

أمر واحد يضيفها إلى وكلاء البرمجة المدعومين.

3

استخدم رسالة البداية

انسخها كما هي؛ سيبدأ الوكيل بسؤالك عمّا تريد بناءه.

حزمة المهارة المنشورة

اقرأ التعليمات 
mkdir -p .agents/skills
unzip hasanat-builder.skill -d .agents/skills

رسالة البداية — جاهزة للنسخ

انسخ الرسالة كما هي والصقها في وكيل البرمجة. سيبدأ بسؤالك عمّا تريد بناءه، ولا تحتاج إلى تعديل أي جزء. 

ساعدني في بدء مشروع صغير يعمل ضمن حسنات.

ابدأ بسؤالي: ما الذي أريد بناءه؟ لا تطلب مني تعديل هذه الرسالة أو إعادة كتابتها. بعد إجابتي، اسأل سؤالين قصيرين كحد أقصى، وفقط عند الحاجة، لتحديد:

- لمن ستكون النسخة الأولى، وما المشكلة التي تحلها؛
- الفعل المفيد الوحيد الذي يجب أن تدعمه أول صفحة محلية.

بعد ذلك لخّص المرحلة الأولى في جملة واحدة، ثم تابع دون أن تطلب مني إعداد وثيقة متطلبات.

تحقق أولاً مما إذا كانت مهارة hasanat-builder متاحة. إن لم تكن متاحة:

1. نزّل الحزمة الموثقة من https://hasanat.dev/skills/hasanat-builder.skill إلى مجلد مؤقت.
2. اعرض محتوياتها باستخدام unzip -l واشرح باختصار أن المهارة تتضمن تعليمات وسكربتات سيتبعها وكيل البرمجة.
3. اطلب موافقتي قبل تثبيتها، ولا تستبدل مجلد مهارة موجودًا.
4. بعد الموافقة، أنشئ .agents/skills داخل المشروع الحالي وفك الحزمة هناك:

mkdir -p .agents/skills
unzip <temporary-path>/hasanat-builder.skill -d .agents/skills

ثم حمّل مهارة hasanat-builder واتبعها.

اجعل المرحلة الأولى محددة: عرّف نتيجة واحدة مفيدة للصفحة الأولى، انسخ قالب حسنات الرسمي العام عبر HTTPS إلى مجلد جديد، ثبّت الاعتماديات المقفلة، انسخ .env.example، شغّل خادم التطوير، وتحقق من الصفحة في المتصفح. لا تشترط تسجيل GitHub أو OAuth أو D1 أو النشر أو أي أسرار قبل أن أرى صفحة تعمل محليًا. بعد ذلك واصل معي تشكيل الفكرة وتنفيذها.
حمّل حزمة المهارة افتح القالب الرسمي

نقطة النجاح الأولى: صفحة حقيقية تعمل على الرابط المحلي الذي يطبعه Astro. إعداد OAuth وD1 والنشر خطوات لاحقة واختيارية.

ابدأ من الصفر

ابدأ بالقالب الرسمي، وشغّل الصفحة محلياً أولاً، ثم أضف ما يحتاجه مشروعك من React 19 وTailwind CSS v4 وخدمات Cloudflare.

1 أنشئ مشروعك

git clone https://github.com/hasanat-dev/starter my-app
cd my-app && npm install
cp .env.example .env

2 ابدأ التطوير

npm run dev
# → http://localhost:4321

3 إعداد البيئة

# .env
AUTH_URL=https://auth.hasanat.dev
DB=hasanat-my-app-db

4 أرسل تطبيقك

عندما يكون جاهزاً، أرسله عبر hasanat.dev/apps — ستحصل على نطاق فرعي وإدراج في المعرض.

↓ الأقسام أدناه (تسجيل الدخول، قاعدة البيانات، الترجمة...) خاصة بهذا المسار.

عندي تطبيق جاهز

عندك تطبيق إسلامي وتريد إدراجه في حسنات؟ أهلاً وسهلاً — لا تحتاج لتغيير أي شيء في كودك.

1 أرسل تطبيقك

اذهب إلى hasanat.dev/apps واضغط زر الإضافة. أدخل اسم تطبيقك، رابطه، ووصفه بالعربية والإنجليزية.

2 احصل على نطاق فرعي

اختر نطاقاً فرعياً مثل myapp.hasanat.dev — نوجّهه لموقعك الحالي. يبقى موقعك على استضافتك الأصلية.

3 اختياري: ربط تسجيل الدخول

إذا تريد أن يستخدم مستخدموك نفس حساب حسنات، يمكنك ربط auth.hasanat.dev. انظر قسم: تسجيل الدخول أدناه.

أستخدم أداة بناء

لا تحتاج أن تكتب كود لتبني على حسنات. استخدم أي أداة تناسبك ثم أرسل تطبيقك:

Replit

replit.com

بيئة تطوير متكاملة في المتصفح — ابنِ ونشِر مباشرة

Lovable

lovable.dev

صِف تطبيقك بالكلام واحصل على كود جاهز

Bolt

bolt.new

أنشئ تطبيقات ويب كاملة من وصف نصي

v0

v0.dev

صمم واجهات React باستخدام الذكاء الاصطناعي

الخطوات

  1. 1 ابنِ تطبيقك باستخدام أي أداة تناسبك من الأدوات أعلاه (أو أي أداة أخرى)
  2. 2 انشر تطبيقك على أي منصة — Replit يوفر استضافة مباشرة، أو استخدم Vercel أو Netlify أو أي منصة أخرى
  3. 3 أرسل تطبيقك عبر hasanat.dev/apps — اختر "استضافة خارجية" وأدخل رابط موقعك
  4. 4 احصل على نطاق فرعي .hasanat.dev يشير إلى موقعك
نصيحة: أدوات البناء مثالية للمشاريع البسيطة. إذا احتجت ميزات متقدمة (تسجيل دخول موحد، قاعدة بيانات D1) يمكنك الانتقال لقالب البداية لاحقاً.

تسجيل الدخول

auth.hasanat.dev يوفر تسجيل دخول موحد عبر جميع تطبيقات حسنات. يدعم Google و GitHub.

وضع الكوكي المشترك (تطبيقات Cloudflare)

إذا كان تطبيقك مستضافاً على Cloudflare Pages تحت نطاق .hasanat.dev، فالمستخدم يسجل دخوله مرة واحدة ويعمل الكوكي تلقائياً.

// src/middleware.ts
import { verifySession } from "./lib/auth";

export async function onRequest(context, next) {
const user = await verifySession(context.request);
context.locals.user = user; // null if not logged in
return next();
}

الوصول للمستخدم الحالي

// In any .astro page or API route
const user = (Astro.locals as any).user;

if (user) {
console.log(user.id); // unique user ID
console.log(user.name); // display name
console.log(user.email); // email
console.log(user.image); // avatar URL
}

حماية الصفحات

// src/pages/api/my-data.ts
export const GET: APIRoute = async ({ locals }) => {
const user = (locals as any).user;
if (!user) return new Response("Unauthorized", { status: 401 });

// user is authenticated, proceed...
};

زر تسجيل الدخول

<!-- Redirect to auth.hasanat.dev -->
<a href="https://auth.hasanat.dev/api/auth/signin">
سجل الدخول
</a>

قاعدة البيانات

Cloudflare D1 — قاعدة بيانات SQLite على الحافة (edge). سريعة، مجانية، وجاهزة للاستخدام.

الاستخدام الأساسي

// Access D1 binding
import { env } from "cloudflare:workers";
const db = env.DB;

// Query
const { results } = await db
.prepare("SELECT * FROM items WHERE user_id = ?")
.bind(userId)
.all();

// Insert
await db
.prepare("INSERT INTO items (name, user_id) VALUES (?, ?)")
.bind(name, userId)
.run();

اصطلاحات التصميم

CREATE TABLE items (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name_ar TEXT NOT NULL, -- Arabic name
name_en TEXT, -- English (optional)
user_id TEXT, -- from auth session
status TEXT DEFAULT 'active',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

استخدم أعمدة ثنائية اللغة (name_ar + name_en) لكل نص يظهر للمستخدم.

ترحيل البيانات

# Create a migration
npx wrangler d1 migrations create my-db add-items

# Apply locally
npx wrangler d1 migrations apply my-db --local

# Apply to production
npx wrangler d1 migrations apply my-db --remote

الترجمة والاتجاهات

حسنات يدعم العربية (الافتراضي) والإنجليزية. كل نص يظهر للمستخدم يجب أن يكون مترجماً.

ملفات الترجمة

src/i18n/
├── ar.json # Arabic translations
├── en.json # English translations
└── utils.ts # useTranslations(), getLocalizedPath()

استخدام الترجمة

// In .astro files
import { useTranslations } from "../i18n/utils";
const t = useTranslations(locale);

<h1>{t("page.title")}</h1>

CSS المنطقي لـ RTL

استخدم خصائص Tailwind المنطقية بدلاً من left/right لضمان عمل الاتجاهين:

لا تستخدم استخدم
ml-4ms-4
mr-4me-4
pl-4ps-4
pr-4pe-4
left-0start-0
right-0end-0
text-lefttext-start

النشر

انشر تطبيقك مجاناً على Cloudflare Pages — أو استخدم أي منصة استضافة أخرى.

wrangler.toml

name = "my-hasanat-app"
compatibility_date = "2024-12-01"
pages_build_output_dir = "./dist"

[[d1_databases]]
binding = "DB"
database_name = "my-app-db"
database_id = "your-d1-id"

أوامر النشر

# Build
npm run build

# Deploy to Cloudflare Pages
npx wrangler pages deploy dist

# Or connect GitHub for auto-deploy
# Cloudflare Dashboard → Pages → Create → Connect to Git

النطاق الفرعي

بعد إرسال تطبيقك عبر صفحة التطبيقات، يمكنك طلب نطاق فرعي مثل myapp.hasanat.dev. فريق حسنات يراجع الطلب ويُعدّ النطاق لك.

استضافة خارجية؟

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

نظام التصميم

هوية حسنات البصرية: ألوان، خطوط، ومبادئ التصميم.

الألوان

hasanat-50

#f0fdfa

hasanat-100

#ccfbf1

hasanat-600

#0f766e

hasanat-700

#115e59

تستخدم الألوان عبر Tailwind CSS: bg-hasanat-600, text-hasanat-600, border-hasanat-200 إلخ.

الخطوط

العناوين

font-display (Playfair Display)

النص الأساسي

System font stack (sans-serif)

مبادئ التصميم

  • ● عربي أولاً، RTL افتراضياً
  • ● جماليات إسلامية: لوحة الزمرد/التيل، صور محتشمة
  • ● الوضوح فوق الزخرفة
  • ● سهولة الوصول: حالات التركيز، التباين، قارئات الشاشة
  • ● الوضع الداكن مدعوم كاملاً

أداة جمع الملاحظات

أضف زر ملاحظات عائم إلى أي موقع — حتى لو لم يكن مبنياً على حسنات. تصل الملاحظات مباشرة إلى مساحة عمل مشروعك.

1. أضف السكربت

ضع هذا السطر قبل إغلاق وسم body. استبدل YOUR_PROJECT_ID بمعرّف مشروعك (تجده في مساحة عمل المشروع). 

<script src="https://hasanat.dev/widget/feedback.js"
        data-project="YOUR_PROJECT_ID" defer></script>

2. اعرض الملاحظات

افتح مساحة عمل مشروعك وانتقل إلى لوحة الملاحظات لرؤية كل ما يرسله المستخدمون. ستجد هناك أيضاً مقتطف التضمين الجاهز مع معرّف مشروعك.

اذهب إلى مشاريعي ←
استخدم قالب البداية ← ارجع لصفحة البُناة