دليل البُناة

كل ما تحتاجه لبناء تطبيقك على منصة حسنات

ابدأ من الصفر

ابدأ مشروعك في أقل من 5 دقائق باستخدام قالب البداية — مُعدّ مسبقاً مع Astro 5 + React 19 + Tailwind CSS v4 + Cloudflare D1.

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 افتراضياً
  • ● جماليات إسلامية: لوحة الزمرد/التيل، صور محتشمة
  • ● الوضوح فوق الزخرفة
  • ● سهولة الوصول: حالات التركيز، التباين، قارئات الشاشة
  • ● الوضع الداكن مدعوم كاملاً
⬇ حمّل قالب البداية ← ارجع لصفحة البُناة