يُعد المصادقة حجر الزاوية لأي تطبيق ويب حديث، ومع ذلك يظل إعداده أحد أكثر التحديات التي تستغرق وقتًا طويلاً التي يواجهها المطورون. نقدم لكم **Better Auth API**—حل مصادقة مستقل عن الأطر البرمجية يعد بتحويل طريقة تنفيذنا لإدارة المستخدمين. في هذا الدليل الشامل، سنتناول بناء تطبيق كامل متكامل يوضح قوة وبساطة Better Auth، باستخدام Bun لأداء فائق السرعة.
هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بـ أقصى إنتاجية؟
Apidog يلبي جميع متطلباتك، و يحل محل Postman بسعر أقل بكثير!
ما هو Better Auth API؟
Better Auth API هو إطار عمل مصادقة حديث ومفتوح المصدر مصمم للعمل بسلاسة عبر أي بيئة JavaScript. على عكس مكتبات المصادقة التقليدية التي تقيدك بأنظمة بيئية محددة، يوفر Better Auth واجهة برمجة تطبيقات موحدة تتكيف مع حزمة التقنيات الخاصة بك—سواء كنت تستخدم React أو Vue أو Svelte أو JavaScript العادي في الواجهة الأمامية، و Node.js أو Bun أو Deno في الواجهة الخلفية. تدعم بنيته القائمة على المكونات الإضافية استراتيجيات مصادقة متعددة، من البريد الإلكتروني/كلمة المرور التقليدية إلى موفري OAuth، ومفاتيح المرور (passkeys)، والروابط السحرية (magic links)، كل ذلك مع الحفاظ على سلامة الأنواع (type safety) وتجربة مطور ممتازة.
البدء باستخدام Better Auth: المتطلبات الأساسية وإعداد المشروع
قبل الخوض في الكود، تأكد من تثبيت ما يلي:
- Bun 1.0+: سنستخدم Bun في هذا البرنامج التعليمي بأكمله لسرعته الاستثنائية وأدواته الحديثة.
- Node.js 18+: مطلوب لوقت تشغيل الواجهة الخلفية.
- محرر أكواد: يوصى بـ VS Code لدعم TypeScript.
بينما يعمل هذا الإعداد بشكل مثالي مع npm، سنعرض سير عمل Bun، الذي يوفر تثبيتًا أسرع للحزم بمقدار 3-5 مرات وتجربة تطوير أكثر سلاسة.
بناء مشروع نموذجي: تنفيذ خطوة بخطوة
دعنا ننشئ نظام مصادقة عملي بواجهة أمامية مبنية بـ React وواجهة خلفية مبنية بـ Express، مع استمرارية قاعدة البيانات.
الخطوة 1: إعداد الواجهة الخلفية باستخدام Express و Drizzle ORM
1. تهيئة مشروع الواجهة الخلفية
أولاً، أنشئ دليل الواجهة الخلفية الخاص بك وادخله:
mkdir better-auth-backend
cd better-auth-backend
bun init -y
2. تثبيت التبعيات
سنحتاج إلى Express للخادم، و Better Auth للمصادقة، و Drizzle ORM لإدارة قاعدة البيانات:
bun add express better-auth drizzle-orm
bun add -D @types/bun @types/express drizzle-kit
3. تكوين متغيرات البيئة
أنشئ ملف `.env` لتخزين التكوينات الحساسة:
BETTER_AUTH_SECRET=your-secret-key-here # Generate with: openssl rand -base64 32
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=local.db
يمكن أيضًا إنشاء *BETTER_AUTH_SECRET* من موقع better-auth الإلكتروني.
4. إنشاء مخطط قاعدة البيانات باستخدام Drizzle ORM
يعمل Better Auth بشكل أفضل مع Drizzle، الذي يوفر دعمًا ممتازًا لـ TypeScript ويتجنب مشكلات الوحدات الأصلية. أنشئ `src/db/schema.ts`:
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
export const user = sqliteTable("user", {
id: text("id").primaryKey(),
name: text('name').notNull(),
email: text('email').notNull().unique(),
emailVerified: integer('email_verified', { mode: 'boolean' }).notNull().default(false),
image: text('image'),
createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull(),
});
export const session = sqliteTable("session", {
id: text("id").primaryKey(),
expiresAt: integer('expires_at', { mode: 'timestamp' }).notNull(),
token: text('token').notNull().unique(),
createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
userId: text('user_id').notNull(),
});
export const account = sqliteTable("account", {
id: text("id").primaryKey(),
accountId: text('account_id').notNull(),
providerId: text('provider_id').notNull(),
userId: text('user_id').notNull(),
accessToken: text('access_token'),
refreshToken: text('refresh_token'),
createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
});
export const verification = sqliteTable("verification", {
id: text("id").primaryKey(),
identifier: text('identifier').notNull(),
value: text('value').notNull(),
expiresAt: integer('expires_at', { mode: 'timestamp' }).notNull(),
});
5. تكوين اتصال قاعدة البيانات
أنشئ `src/db/index.ts` باستخدام ربط SQLite الأصلي لـ Bun:
import { Database } from "bun:sqlite";
import { drizzle } from "drizzle-orm/bun-sqlite";
const sqlite = new Database("local.db");
export const db = drizzle(sqlite);
6. إعداد تكوين Better Auth
أنشئ `src/lib/auth.ts` لتكوين Better Auth API:
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { db } from "../db";
import { user, session, account, verification } from "../db/schema";
export const auth = betterAuth({
database: drizzleAdapter(db, {
provider: "sqlite",
schema: {
user: user,
session: session,
account: account,
verification: verification,
},
}),
emailAndPassword: {
enabled: true,
},
trustedOrigins: ["http://localhost:5173"],
});
7. إنشاء خادم Express
في `src/index.ts`، قم بتركيب معالج Better Auth API:
import express from "express";
import cors from "cors";
import { toNodeHandler } from "better-auth/node";
import { auth } from "./lib/auth";
const app = express();
const PORT = process.env.PORT || 3000;
app.use(
cors({
origin: "http://localhost:5173",
credentials: true,
})
);
// Mount Better Auth API at /api/auth
app.use("/api/auth", toNodeHandler(auth));
app.use(express.json());
app.get("/api/me", async (req, res) => {
const session = await auth.api.getSession({
headers: req.headers,
});
if (!session) {
return res.status(401).json({ error: "Unauthorized" });
}
res.json({ user: session.user });
});
app.listen(PORT, () => {
console.log(`Server running on http://localhost:${PORT}`);
});
8. تشغيل ترحيل قاعدة البيانات
أنشئ `drizzle.config.ts` في جذر الواجهة الخلفية:
import { defineConfig } from "drizzle-kit";
export default defineConfig({
dialect: "sqlite",
schema: "./src/db/schema.ts",
out: "./drizzle",
dbCredentials: {
url: "local.db",
},
});
نفّذ الترحيل لإنشاء الجداول:
bunx drizzle-kit push
الخطوة 2: إعداد الواجهة الأمامية باستخدام React و Vite
1. إنشاء تطبيق React
في طرفية جديدة، قم بتهيئة الواجهة الأمامية:
bun create vite better-auth-frontend --template react-ts
cd better-auth-frontend
2. تثبيت التبعيات
bun add better-auth
3. تكوين Tailwind CSS (تحديث الإصدار 4)
يتطلب Tailwind CSS v4 وما بعده إعدادًا مختلفًا. قم بتثبيت الحزم الجديدة:
bun add -D tailwindcss postcss @tailwindcss/postcss
أنشئ `tailwind.config.js` في جذر المشروع:
/** @type {import('tailwindcss').Config} */
export default {
content: [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme: {
extend: {},
},
plugins: [],
}
أنشئ `postcss.config.js`:
export default {
plugins: {
"@tailwindcss/postcss": {},
},
}
أنشئ `src/index.css`:
@import "tailwindcss";
body {
margin: 0;
font-family: system-ui, -apple-system, sans-serif;
}
4. إعداد عميل Better Auth
أنشئ `src/lib/auth-client.ts`:
import { createAuthClient } from "better-auth/react";
export const authClient = createAuthClient({
baseURL: "http://localhost:3000",
});
export const { signIn, signUp, useSession } = authClient;
5. بناء واجهة المستخدم للمصادقة
استبدل `src/App.tsx` بواجهة مصادقة كاملة:
import { useState } from 'react';
import { useSession, signIn, signUp } from './lib/auth-client';
function App() {
const { data: session, isPending } = useSession();
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const [name, setName] = useState('');
const handleSignUp = async (e: React.FormEvent) => {
e.preventDefault();
await signUp.email({
name,
email,
password,
callbackURL: '/',
});
};
const handleSignIn = async (e: React.FormEvent) => {
e.preventDefault();
await signIn.email({
email,
password,
});
};
const handleSignOut = async () => {
await authClient.signOut();
};
if (isPending) return <div className="flex items-center justify-center min-h-screen">جار التحميل...</div>;
return (
<div className="min-h-screen bg-gray-100 flex items-center justify-center p-4">
<div className="max-w-md w-full bg-white rounded-lg shadow-md p-6">
<h1 className="text-2xl font-bold text-center mb-6 text-gray-800">
اختبار Better Auth API
</h1>
{session?.user ? (
<div className="space-y-4">
<div className="bg-green-50 p-4 rounded-md">
<p className="text-green-800 font-semibold">مسجل الدخول باسم:</p>
<p className="text-green-700">{session.user.email}</p>
<p className="text-green-600 text-sm">{session.user.name}</p>
</div>
<button
onClick={handleSignOut}
className="w-full bg-red-500 hover:bg-red-600 text-white font-medium py-2 px-4 rounded-md transition"
>
تسجيل الخروج
</button>
</div>
) : (
<div className="space-y-4">
<form onSubmit={handleSignUp} className="space-y-3">
<h2 className="text-lg font-semibold text-gray-700">التسجيل</h2>
<input
type="text"
placeholder="الاسم"
value={name}
onChange={(e) => setName(e.target.value)}
className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
required
/>
<input
type="email"
placeholder="البريد الإلكتروني"
value={email}
onChange={(e) => setEmail(e.target.value)}
className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
required
/>
<input
type="password"
placeholder="كلمة المرور"
value={password}
onChange={(e) => setPassword(e.target.value)}
className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
required
/>
<button
type="submit"
className="w-full bg-green-500 hover:bg-green-600 text-white font-medium py-2 px-4 rounded-md transition"
>
إنشاء حساب
</button>
</form>
<form onSubmit={handleSignIn} className="space-y-3">
<h2 className="text-lg font-semibold text-gray-700">تسجيل الدخول</h2>
<input
type="email"
placeholder="البريد الإلكتروني"
value={email}
onChange={(e) => setEmail(e.target.value)}
className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
required
/>
<input
type="password"
placeholder="كلمة المرور"
value={password}
onChange={(e) => setPassword(e.target.value)}
className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
required
/>
<button
type="submit"
className="w-full bg-blue-500 hover:bg-blue-600 text-white font-medium py-2 px-4 rounded-md transition"
>
تسجيل الدخول
</button>
</form>
</div>
)}
</div>
</div>
);
}
export default App;
الخطوة 3: اختبار التكامل
1. تشغيل خادم الواجهة الخلفية
cd better-auth-backend
bun dev
2. بدء تطوير الواجهة الأمامية
cd better-auth-frontend
bun dev
3. اختبار تدفق المصادقة
- افتح `http://localhost:5173` في متصفحك
- سجل مستخدمًا جديدًا باستخدام نموذج التسجيل
- لاحظ نمو ملف قاعدة البيانات مع تعبئة الجداول
- سجّل الخروج ثم سجّل الدخول مرة أخرى للتحقق من إدارة الجلسات
- تحقق من نقطة نهاية الجلسة: `http://localhost:3000/api/auth/session`
الفوائد الرئيسية لـ Better Auth API
يتميز **Better Auth API** بالعديد من المزايا الجذابة:
- استقلالية الإطار: على عكس NextAuth.js أو Firebase Auth، يعمل Better Auth في أي مكان يعمل فيه JavaScript. تخدم نفس منطق المصادقة عملاء الويب والجوال وواجهات برمجة التطبيقات دون تعديل.
- استراتيجيات مصادقة متعددة: دعم جاهز للاستخدام لبيانات الاعتماد، OAuth 2.0، مفاتيح المرور (passkeys)، المصادقة الثنائية، والروابط السحرية (magic links). كل استراتيجية هي مكون إضافي يمكن تفعيله بسطر تكوين واحد.
- سلامة الأنواع (Type Safety): دعم TypeScript الكامل مع أنواع مستنتجة من مخطط قاعدة البيانات الخاص بك يزيل مشكلة نوع "any" الشائعة في قواعد أكواد المصادقة.
- مرونة قاعدة البيانات: محول Drizzle ORM يعني أنه يمكنك التبديل بين SQLite و PostgreSQL و MySQL دون تغيير منطق المصادقة الخاص بك. يستخدم هذا البرنامج التعليمي SQLite للتبسيط، ولكن نفس الكود يتوسع ليناسب قواعد بيانات الإنتاج.
- نظام المكونات الإضافية: هل تحتاج إلى دعم التنظيم؟ تعدد المستأجرين (Multi-tenancy)؟ أدوار المسؤول؟ يتيح لك نظام المكونات الإضافية في Better Auth توسيع الوظائف دون تضخيم النواة.
- الأداء: مع Bun كوقت تشغيل، تكون أوقات البدء الباردة أقل من 100 مللي ثانية، ويكتمل تدفق المصادقة بأكمله في أقل من 50 مللي ثانية على أجهزة متواضعة.
الأسئلة المتداولة
س1: هل يمكنني استخدام Better Auth API مع npm بدلاً من Bun؟
ج: بالتأكيد. بينما يستخدم هذا الدليل Bun لفوائده المتعلقة بالأداء، فإن كل أمر له مكافئ في npm. استبدل `bun add` بـ `npm install`، و `bun dev` بـ `npm run dev`، و `bunx` بـ `npx`. الكود الوحيد الخاص بـ Bun هو استيراد `bun:sqlite`، والذي يمكن استبداله بـ `better-sqlite3` لبيئات Node.js.
س2: لماذا احتجنا إلى Drizzle ORM؟ ألا يستطيع Better Auth إنشاء الجداول تلقائيًا؟
ج: يتبع Better Auth مبدأ إدارة قاعدة البيانات الصريحة. يوفر Drizzle ترحيلات آمنة للأنواع (type-safe migrations)، وتحديد إصدارات المخطط (schema versioning)، ويمنع فقدان البيانات العرضي. يعد الأمر `drizzle-kit push` إعدادًا لمرة واحدة يمنحك تحكمًا كاملاً في تطور قاعدة بياناتك.
س3: ماذا لو واجهت خطأ "Missing parameter name"؟
ج: يحدث هذا عند استخدام `app.all()` مع أحرف البدل (wildcards) في Express. الحل هو استخدام `app.use("/api/auth", toNodeHandler(auth))` بدلاً من ذلك. يتعامل معالج Better Auth مع جميع المسارات الفرعية داخليًا، لذلك لا يحتاج Express إلى مطابقة أحرف البدل.
س4: كيف أضيف موفري مصادقة اجتماعية؟
ج: قم بتمكين مكونات OAuth الإضافية في تكوين Better Auth الخاص بك. على سبيل المثال، لإضافة GitHub:
import { betterAuth } from "better-auth";
import { github } from "better-auth/plugins";
export const auth = betterAuth({
plugins: [
github({
clientId: process.env.GITHUB_CLIENT_ID,
clientSecret: process.env.GITHUB_CLIENT_SECRET,
})
]
});
س5: هل Better Auth API جاهز للإنتاج؟
ج: نعم. يدعم Better Auth المصادقة للعديد من منتجات SaaS التي تضم آلاف المستخدمين. ينفذ الإطار إدارة جلسات آمنة، وحماية من هجمات CSRF، ويتبع إرشادات OWASP. ومع ذلك، قم دائمًا بمراجعة تطبيقك الخاص وحافظ على تحديث التبعيات.
الخاتمة
لم يعد بناء المصادقة من الصفر ضروريًا مع الحلول الحديثة مثل **Better Auth API**. في هذا الدليل، أنشأنا نظام مصادقة كاملاً—من مخطط قاعدة البيانات إلى مكونات واجهة المستخدم—في بضع دقائق! يخلق الجمع بين مرونة Better Auth، وسلامة الأنواع في Drizzle ORM، وأداء Bun تجربة مطور تتوسع من النموذج الأولي إلى الإنتاج.
توضح العملية خطوة بخطوة أن المصادقة، على الرغم من أهميتها، لا تحتاج إلى أن تكون معقدة. من خلال الاستفادة من بنية المكونات الإضافية لـ Better Auth وتصميمه المستقل عن الأطر، يمكنك التركيز على بناء الميزات التي تهم المستخدمين بدلاً من الصراع مع تطبيقات الأمان.
سواء كنت تبني مشروعًا جانبيًا أو تطبيقًا للمؤسسات، يوفر Better Auth API الأساس لمصادقة آمنة وقابلة للتطوير تتكيف مع احتياجاتك—وليس العكس.
هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بـ أقصى إنتاجية؟
Apidog يلبي جميع متطلباتك، و يحل محل Postman بسعر أقل بكثير!