بناء بنية تطبيق full stack حديثة باستخدام Next.js 15+
يستعرض هذا المقال خطوة بخطوة بنية تطبيق full stack حديثة مبنية بـ Next.js 15 مع تقنيات مثل TypeScript وServer Actions ومكوّنات الخادم والعميل (Server and Client Components) وAuth.js وTailwind CSS وDrizzle ORM وPostgreSQL وDocker.
تحظى مكتبة React منذ سنوات طويلة بشعبية كبيرة في عالم الواجهات الأمامية. فهي تتيح للمطورين إنشاء واجهات مستخدم تفاعلية من مكوّنات قابلة لإعادة الاستخدام ويمكن دمجها بعضها مع بعض. وبفضل هذا النهج المعياري يصبح التطبيق قابلاً للتوسع وسهل الصيانة.
ولأن React مكتبة، فهي تترك للمطورين اختيار أدوات إضافية لأمور مثل التوجيه (routing) وإدارة الحالة وجلب البيانات والتخزين المؤقت واستراتيجيات عرض الصفحات. وتمنح هذه المرونة حرية كبيرة. لكنها عملياً تعني اتخاذ قرارات معمارية: كيف ننظم المجلدات والملفات، وأي اصطلاحات تسمية نتبع، وكيف نؤمّن التطبيق على مستوى SSR، وكيف نتعامل مع SEO، وأخيراً لا آخراً، كيف نعتني بتجربة المطور. ونتيجة لذلك، يضطر المطورون إلى قضاء وقت في إعداد الأدوات وإعادة ابتكار حلول لمتطلبات التطبيقات الشائعة.
مقدمة
من بين أطر العمل التي توفر هذا الإعداد والأدوات «جاهزة للاستخدام»، يتصدر Next.js المشهد. فهو حالياً أنضج إطار عمل، مما يجعله خياراً بديهياً إلى حد كبير، خصوصاً لمطوري React أو لكل من يريد بناء تطبيقات ضمن منظومة React.
يعامل Next.js العرض من جهة الخادم (SSR) بوصفه تقنية العرض الرئيسية. كما يدعم توليد المواقع الثابتة (SSG) والتجديد الثابت التدريجي (ISR) والعرض من جهة العميل (CSR). وإضافة إلى ذلك، يوفر مكوّنات الخادم في React (RSC) ودوال الخادم في React (RSF) كلبنات معمارية أساسية. ويتيح Next.js أيضاً الجمع بين تقنيات العرض هذه بحرية – فصفحة الهبوط (landing page) مثلاً يمكن أن تعتمد على SSG، بينما يمكن لتطبيق مع مصادقة (لوحة تحكم) أن يعتمد على SSR.
تتيح لك React وحدها بناء تطبيقات تعمل حصراً من جهة العميل. وإذا احتاج تطبيق كهذا إلى واجهة خلفية (للتعامل مع استعلامات قاعدة البيانات أو المصادقة مثلاً)، فيجب بناء تلك الواجهة الخلفية بشكل منفصل ودمجها مع تطبيق React. أما Next.js فعلى العكس، يتيح بناء تطبيقات full-stack، فيعمل المطور على الواجهة الأمامية والخلفية معاً ضمن إطار عمل واحد.
الميزات الرئيسية في Next.js
- SSR – دعم مدمج لعرض الصفحات من جهة الخادم، مما يعزز الأداء وSEO
- SSG – دعم توليد المواقع الثابتة، حيث تُنتَج الصفحات وقت الترجمة وتُقدَّم كملفات HTML ثابتة، مما يسرّع التحميل ويخفف الحمل على الخادم
- التقسيم التلقائي للشيفرة (Automatic code splitting) – يقسّم Next.js الشيفرة إلى أجزاء أصغر وأسهل في الإدارة لتحسين الأداء ووقت التحميل
- دعم CSS – دعم مجموعة من حلول CSS، منها وحدات CSS ومكتبات CSS-in-JS وأنماط CSS العامة، مما يوفر مرونة في تنسيق التطبيق
- جلب البيانات – دعم عدة طرق لجلب البيانات وقت الترجمة أو وقت الطلب
- التوجيه – أصبح أبسط بكثير بفضل التوليد التلقائي للمسارات بناءً على بنية الملفات ومجلدات الصفحات
- تحسين الصور – تغيير حجم الصور وضغطها تلقائياً لضمان أداء تحميل مثالي
- تجميع CSS وJavaScript المدمج – تُحسَّن CSS وJS وتُجمَّع تلقائياً لتُحمَّل بكفاءة أكبر
- وكالة API (API proxying) – تتيح إنشاء مسارات API تعمل كوسيط لواجهات برمجية تابعة لجهات خارجية، مما يساعد في جلب البيانات والأمان
- دعم التدويل – يوفر Next.js أدوات ومكتبات لدعم لغات متعددة
وبالنظر إلى هذه الميزات والمزايا، يجدر التساؤل عن الحالات التي يكون فيها اختيار هذا الإطار منطقياً بدلاً من React العادية. يفيد Next.js في المواقع كثيفة المحتوى مثل المدونات أو التجارة الإلكترونية، حيث يهم SEO كثيراً أيضاً. ويمكن لـ Next.js تحسين أداء التطبيق بشكل ملحوظ، إذ لا يضطر المستخدم إلى تنزيل وتنفيذ كميات كبيرة من JS على جهازه – وهذا مهم خصوصاً على الأجهزة أو الشبكات الأبطأ.
وعليه، يكون الاكتفاء بـ React العادية هو الخيار الأفضل حين نتعامل مع:
- بنية خدمات مصغّرة، أو منطق يعتمد بشدة على الواجهة الخلفية
- تطبيق يعتمد بشدة على التحديثات الفورية
- واجهة مستخدم مخصصة بدرجة عالية بعناصر مثل الرسوم المتحركة والتفاعلات والتخطيطات المعقدة
بعد انتهاء المقدمة، حان وقت الدخول في التفاصيل. سأستعرض بقية المفاهيم التي ينبغي للمطور أن يضعها في الحسبان عند بناء تطبيق Next.js، وذلك بتهيئة وإعداد تطبيق ينفذ عمليات CRUD على المقالات، مع المصادقة.
بدء المشروع
في الطرفية:
npx create-next-app@latest
بعد تشغيل الأمر، نجيب عن بضعة أسئلة، وبعد وقت قصير يُعدّ كل ما نحتاجه تلقائياً.
بنية المشروع
يسأل أحد الأسئلة عن الموجّه (router) الذي سيُستخدم. يقدم Next.js نوعين:
- App Router – الموجّه الأحدث، ويدعم ميزات React الجديدة مثل Server Components وServer Actions،
- Pages Router – يعتمد على موجّه نظام الملفات الذي يربط كل ملف بمسار. وحتى الإصدار 13 كان الطريقة الأساسية لإنشاء المسارات، وما زالت الإصدارات الأحدث تدعمه.
قبل أن يقدم Next.js الموجّه App Router، كان التوجيه داخل التطبيق مبنياً على Pages Router. وفي جوهره كان يعتمد على React Router المدمج في Next.js لمعالجة التنقل بين الصفحات تلقائياً.
بتقنية Pages Router، تنشئ ملفات .js أو .ts في مجلد pages، ويحوّلها Next.js تلقائياً إلى صفحات فرعية في التطبيق. فإنشاء بنية مثل pages/users.ts، مثلاً، ينتج صفحة على المسار /users.
حين يلزم أن يذهب طلب إلى الخادم في Pages Router، يمكن استخدام الدالتين getServerSideProps أو getStaticProps داخل ملفات pages.
أما App Router – وهو النهج الأحدث (منذ الإصدار 13) والموصى به – فيمنح المطورين تحكماً ومرونة أكبر. فهو يعرّف المسارات بالمجلدات، مما يتيح ميزات أكثر تقدماً مثل التخطيطات المتداخلة (nested layouts).
بالنظر إلى بنية app/users/page.ts، تكون الصفحة مكوّن خادم افتراضياً (تعمل على الخادم)، ويصبح المسار /users هو المسار الفعلي. ويمكنك أيضاً إنشاء تخطيطات (layouts) مشتركة بين عدة مسارات، مما يساعد على الحفاظ على اتساق التصميم والبنية في التطبيق كله.
يعطي Next.js معنى خاصاً لبعض أسماء المجلدات والملفات المحجوزة. فبالنسبة إلى المجلدات تشمل: src وpublic وapp و[folder] و[…folder]. وبالنسبة إلى الملفات، من الأمثلة (بالامتدادات .ts و.js و.tsx و.jsx على التوالي): middleware وlayout وpage وloading وerror. ويحدد موضعها في بنية المشروع كيفية عرض الصفحات والمكوّنات وكيف يتصرف التطبيق ككل.
ستجد المزيد من التفاصيل هنا: بنية المشروع وتنظيمه
Server Actions
في النهج الأحدث، تُعالَج المهام من جهة الخادم، مثل جلب البيانات وإرسال النماذج والتفاعل مع قاعدة البيانات، عبر Server Actions. وفي App Router، يكون كل طلب من جهة الخادم افتراضياً، مما يجعل التواصل مع الخادم قبل عرض الصفحة أبسط. ويمكن استدعاء Server Actions من كل من مكوّنات الخادم (Server) ومكوّنات العميل (Client Components).
تُعلَن Server Actions بالتوجيه ‘use server’. إذ يجب إخبار Next.js بأن دالة ما، أو كل تصدير في ملف، ينبغي معاملته على أنه Server Action. وبدون هذا التوجيه، لا يستطيع Next.js معرفة ما إذا كانت الدالة محلية (تستخدمها مكوّنات الخادم فقط) أو ما إذا كان ينبغي كشفها كـ Server Action يمكن للعميل استدعاؤها. وهذا مقصود في التصميم، لأن Next.js يتيح المزج بين مكوّنات العميل والخادم بطريقة هجينة – ولا يمكن استدعاء الدوال من العميل إلا إذا وُسمت بالتوجيه ‘use server’.
على سبيل المثال:
'use server';
import { eq } from 'drizzle-orm';
import db from '@/db';
import { articles } from '@/db/schema';
export async function getArticleBySlug(slug: string) {
return await db.query.articles.findFirst({
where: eq(articles.slug, slug),
});
}
بفضل التوجيه ‘use server’، يمكن استدعاء الدالة getArticleBySlug من كل من:
مكوّن الخادم (Server Component):
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { slug } = await params;
const data = await getArticleBySlug(slug);
// ...
}
ومكوّن العميل (Client Component) (مثلاً بتمرير الدالة كدالة رد نداء (callback) إلى معالج حدث أو داخل useEffect):
أو:
'use client';
import { createArticle } from '@/lib/actions/article.actions';
// ...
export const ArticleForm = () => {
return (
<form action={createArticle}>
{/* ... */}
<button type='submit'>Create</button>
</form>
);
};
أو:
'use client';
import { createArticle } from '@/lib/actions/article.actions';
// ...
export const ArticleForm = () => {
return (
<>
{/* ... */}
<button
onClick={async () => {
const formData = new FormData();
formData.append('title', 'Article title');
await createArticle(formData);
}}
>
Create
</button>
</>
);
};
بدون التوجيه ‘use server’، قد يعامل Next.js هذه الدالة كدالة مساعدة عادية. ونتيجة لذلك، لن تُسجَّل كـ Server Action ولن يمكن استدعاؤها ديناميكياً من مكوّن العميل.
يمكن وضع التوجيه ‘use server’ إما في أعلى دالة غير متزامنة، فيعلّم تلك الدالة كـ Server Action، أو في أعلى ملف منفصل، فيعلّم كل تصدير في ذلك الملف كـ Server Action:
// Directive at the top of a separate file
'use server';
export async function createArticle(article: Article): Promise<ReturnType> {
const parsedArticle = articleFormSchema.parse(article);
if (!parsedArticle.success) return { message: 'Something went wrong' };
return { message: 'Article created' };
}
// Directive at the top of an async function
export function Page() {
const createArticle = async () => {
'use server';
// ...
};
return <form action={createArticle}>...</form>;
}
مكوّنات الخادم والعميل
لنتناول الآن مسألة متى نلجأ إلى مكوّنات العميل ومتى إلى مكوّنات الخادم.
التخطيطات والصفحات هي مكوّنات خادم افتراضياً. وهذا يتيح لك إرسال الطلبات من الخادم وعرض أجزاء من واجهة المستخدم هناك، مع تخزين النتائج مؤقتاً إن شئت وتمريرها إلى العميل. أما مكوّنات العميل فهي الخيار حين تحتاج إلى التفاعلية أو إلى الوصول إلى واجهة المتصفح البرمجية (browser API). ولإنشاء مكوّن عميل، تضيف التوجيه ‘use client’ في أعلى الملف، فوق عبارات الاستيراد. وما إن يحمل الملف التوجيه ‘use client’ حتى يصبح كل ما يستورده وجميع مكوّناته الفرعية جزءاً من حزمة العميل (client bundle). وهذا يعني أيضاً أنك لست مضطراً إلى وضع التوجيه ‘use client’ في كل مكوّن مخصص للعميل.
متى تستخدم مكوّنات العميل:
- إدارة حالة المكوّن ومعالجة الأحداث (مثل onClick وonChange)
- استخدام دورة حياة المكوّن (مثل useEffect)
- الوصول إلى واجهة المتصفح البرمجية (localStorage وwindow وgeolocation)
- الخطافات المخصصة (Custom hooks)
متى تستخدم مكوّنات الخادم:
- التعامل مع قاعدة البيانات
- العمل مع مفاتيح API والرموز (tokens) وغيرها من البيانات الحساسة التي لا ينبغي أن يصل إليها العميل
- تقليل كمية JavaScript المرسلة إلى المتصفح
- تحسين First Contentful Paint وبث المحتوى إلى العميل تدريجياً
مدير الحزم
لتهيئة المشروع، استخدمنا الأمر npx الذي يشغّل حزم Node.js من سجل npm مباشرة دون تثبيتها عالمياً. وفيما يخص مديري الحزم، يُعد npm الأوسع استخداماً، ويعود ذلك أساساً إلى أنه يأتي مع كل تثبيت لـ Node.js. ومع ذلك، فإن yarn وpnpm وbun بدائل جيدة – وpnpm خصوصاً بفضل أدائه الأفضل.
وإذا احتجت يوماً إلى بناء عدة تطبيقات تعتمد بعضها على بعض أو تتشارك مجموعة مكوّنات مشتركة، فمن المفيد التفكير في monorepo. وقد تكون أدوات مثل Nx أو Turborepo مناسبة لذلك.
أداة التدقيق (Linter) ومنسّق الشيفرة
بعد تهيئة المشروع، تكون الخطوة التالية الجديرة بالاتخاذ هي ضمان أسلوب شيفرة متسق. ويساعد في ذلك مدقق ESLint: فهو يفرض أسلوب شيفرة معيناً ويبلغ عن خطأ في بيئة التطوير (IDE) كلما خُرقت القواعد المحددة.
ويجب أن يُستكمل بمنسّق شيفرة مثل Prettier، الذي يمكن إعداده لتنسيق الشيفرة – وفق قواعد محددة – عند كل حفظ لملف. لا يحل Prettier محل ESLint، لكن الاثنين يتكاملان بشكل جيد.
ثبّت الحزمة بالأمر:
npm install --save-dev eslint-config-prettier
ثم أضف الحزمة إلى ملف إعداد ESLint (eslint.config.mjs).
وأثناء ذلك، لا تنسَ تثبيت حزمة ترتّب عبارات الاستيراد بترتيب محدد. فمثلاً تأتي مكتبات الأطراف الثالثة أولاً، ثم الاستيراد بالأسماء المستعارة (alias)، وأخيراً الاستيراد النسبي، مع فواصل من أسطر فارغة بين المجموعات، مما يحافظ على هذا الجزء من الملف مرتباً ومقروءاً:
npm install --save-dev @trivago/prettier-plugin-sort-imports
بعد ذلك، أضف الحزمة إلى قائمة الإضافات في الملف .prettierrc.json وعرّف قواعد الترتيب:
{
"importOrder": [
"^(react|next?/?([a-zA-Z/]*))$",
"<THIRD_PARTY_MODULES>",
"^@/(.*)$",
"^[./]"
],
"importOrderSeparation": true,
"importOrderSortSpecifiers": true,
"plugins": ["@trivago/prettier-plugin-sort-imports"]
}
التنسيق (Styling)
يأتي التطبيق جاهزاً لـ Tailwind CSS. وبطبيعة الحال، تعتمد طريقة تنسيق التطبيق على احتياجاتك وذوقك. ومع ذلك، يستحق هذا الإطار التجربة بسبب نهجه القائم على الأصناف الأدواتية (utility classes) التي تتركب بسهولة لبناء أي مشروع. وما يميز Tailwind CSS أنه بدلاً من أن يقدم لنا مكوّنات جاهزة، يمنحنا الأدوات لبناء مكوّناتنا الخاصة.
كان النهج التقليدي يعتمد على أصناف مثل container وsection-wrapper وaccordion وheading-1 وnotification وما شابهها. أما Tailwind CSS فليس فيه أصناف من هذا النوع؛ بل يقدم مجموعة من الأدوات البسيطة مثل flex (التي تضبط display: flex) وw-screen (width: 100vw) وtext-lg (التي تضبط حجم خط محدداً وارتفاع سطر محدداً معاً) وهكذا. وأوصي بقراءة الوثائق.
تأتي المشاريع المختلفة بمتطلبات مختلفة لتنسيق واجهة المستخدم، تتراوح بين نظام تصميم محدد يتطلب مكوّنات مخصصة ونهج أكثر مرونة تكفي فيه الحلول الجاهزة. ومن مكتبات المكوّنات الشائعة اليوم shadcn/ui، التي تبني مكوّنات جاهزة من أصناف Tailwind الأساسية. والأهم أنها لا تُثبَّت كاعتماد للمشروع؛ بل توضع الشيفرة في مجلد components، مما يمنحنا الوصول إلى المصدر. وتأتي مكوّنات shadcn/ui بتنسيق أساسي، لذا يسهل تكييفها مع تصميم التطبيق.
ومن المكتبات الجديرة بالذكر أيضاً:
العمل مع متغيرات البيئة
بعد ذلك، لننظر في إعداد طريقة عملنا مع متغيرات البيئة. افتراضياً، يلتقط Next.js الملف .env في المشروع ويحمّل متغيرات البيئة المعرّفة فيه، ويجعلها متاحة عبر process.env. لكن قد يحدث أن يكون متغير مفقوداً أو بنوع خاطئ – فرقم المنفذ (port) مثلاً ينبغي أن يكون رقماً لا سلسلة نصية. ولمعالجة متغيرات البيئة بطريقة آمنة من ناحية الأنواع مع تحقق تلقائي، يُستحسن اللجوء إلى مكتبة Zod، التي تتيح لنا تعريف مخطط (schema) للمتغيرات المطلوبة والتحقق منها عند بدء التطبيق.
ويمكننا أن نخطو خطوة أبعد مع مكتبة T3 Env، المبنية على Zod والمصممة خصيصاً لإدارة متغيرات البيئة في مشاريع TypeScript/Next.js. وهي تتيح لنا أيضاً الفصل بين متغيرات جهة العميل وجهة الخادم.
التثبيت:
npm install @t3-oss/env-nextjs zod
في الملف src/env/server.ts، نعرّف مخططاً لمتغيرات البيئة الخاصة بالخادم:
import { createEnv } from "@t3-oss/env-nextjs";
import "dotenv/config";
import { z } from "zod";
export const env = createEnv({
server: {
NODE_ENV: z.enum(["development", "production"]),
AUTH_GOOGLE_ID: z.string(),
AUTH_GOOGLE_SECRET: z.string(),
SESSION_SECRET: z.string(),
DATABASE_URL: z.string().url(),
CLOUDINARY_NAME: z.string(),
CLOUDINARY_KEY: z.string(),
CLOUDINARY_SECRET: z.string(),
},
onValidationError: (issues) => {
console.error("❌ Invalid environment variables:", issues);
process.exit(1);
},
emptyStringAsUndefined: true,
experimental__runtimeEnv: process.env,
});
عند الحاجة، سأحتفظ بملف منفصل src/env/client.ts للعميل، لأن متغير البيئة يجب أن يحمل البادئة NEXTPUBLIC ليُكشف في المتصفح.
من الجيد استيراد هذا الملف في الملف next.config.ts، بحيث تُفحص متغيرات البيئة وقت الترجمة. وإذا كان أي متغير مفقوداً، فلن يبدأ التطبيق إطلاقاً.
ولمنع تطبيقنا من الوصول إلى process.env مباشرة في أي مكان، ولفرض استخدام المخطط الذي أنشأناه، يمكننا تثبيت إضافة eslint-plugin-n:
npm install –save-dev eslint-plugin-n
وتفعيلها في الملف eslint.config.mjs:
const eslintConfig = [
...compat.config({
plugins: ['n'],
rules: {
"n/no-process-env": ["error"]
}
})
];
ومن الآن فصاعداً، يتطلب الرجوع إلى متغير بيئة استيراد الثابت env الذي عرّفناه سابقاً:
import { env } from “@/env/server”;
ثم استخدامه:
env.DATABASE_URL
التعامل مع النماذج والتحقق من الصحة
النماذج (forms) جزء أساسي من أي تطبيق، والعمل معها يطرح عدداً من التحديات. نحتاج إلى تحقق من جهة العميل لإعطاء المستخدمين ملاحظات فورية، وإلى تحقق من جهة الخادم لضمان سلامة البيانات وإدارة حالة النموذج. وقد يتعقد الأمر بسرعة، خصوصاً مع النماذج متعددة الخطوات أو ذات الحقول الديناميكية. ويمكن للمكتبات المتخصصة التي تقدم نهجاً منظماً للتحقق، وتقلل الشيفرة المتكررة، وتساعد في الحفاظ على اتساق واجهة المستخدم لحالات الخطأ والملاحظات، أن تحسّن تجربة المطور والمستخدم تحسيناً كبيراً.
React Hook Form مكتبة نماذج بارزة تركز على الأداء. وهي مبنية لتقليل إعادة العرض (re-rendering) إلى الحد الأدنى مع الحفاظ على المرونة. ونهجها القائم على الخطافات أولاً يبسّط شجرة المكوّنات ويتجنب إعادة العرض غير الضرورية.
التثبيت:
npm install react-hook-form
وهذا مثال:
import { zodResolver } from "@hookform/resolvers/zod";
import { SubmitHandler, useForm } from "react-hook-form";
import { z } from "zod";
// ...
const {
register,
handleSubmit,
formState: { errors },
} = useForm({
resolver: zodResolver(articleFormSchema),
defaultValues: { ... },
});
const onSubmit: SubmitHandler<z.infer<typeof articleFormSchema>> = async (
values
) => { ... };
return (
<form onSubmit={handleSubmit(onSubmit)}>
<div>
<Input {...register("title", { required: true })} />
<p>{errors.title?.message}</p>
</div>
{/* ... */}
</form>
);
};
تعمل React Hook Form بتناغم مع مكتبات التحقق القائم على المخططات (يستخدم المثال أعلاه zodResolver). تطرقت إلى مكتبة Zod عند الحديث عن متغيرات البيئة، وهي تناسب هذه الحالة تماماً أيضاً. إنها مكتبة تضع TypeScript أولاً وتتيح لنا تعريف مخططات التحقق عبر واجهة برمجية متسلسلة (chainable API) مبنية على نظام استنتاج الأنواع في TypeScript. ومن أبرز نقاط قوة Zod أنها يمكن أن تكون المصدر الوحيد للحقيقة (single source of truth) لمنطق التحقق في العميل والخادم معاً، فنعرّف مخطط التحقق مرة واحدة ونعيد استخدامه في التطبيق كله.
مثال:
import { z } from "zod";
export const signUpFormSchema = z
.object({
name: z.string().min(3, "Name must be at least 3 characters"),
email: z.string().email("Invalid email address"),
password: z.string().min(6, "Password must be at least 6 characters"),
confirmPassword: z
.string()
.min(6, "Confirm password must be at least 6 characters"),
})
.refine((data) => data.password === data.confirmPassword, {
message: "Passwords don't match",
path: ["confirmPassword"],
});
أما للتحقق من جهة الخادم، فتقدم Zod طريقة نظيفة ومباشرة للتحقق من حمولة الطلب:
import { signUpFormSchema } from "@/validations/sign-up.validator";
export async function signup(_state: FormState, formData: FormData) {
try {
const user = signUpFormSchema.parse({
name: formData.get("name"),
email: formData.get("email"),
password: formData.get("password"),
confirmPassword: formData.get("confirmPassword"),
});
// ...
} catch (error) {
// ...
}
}
الاختبار
يُبنى الاختبار على إطار مثل Vitest أو Jest، يوفر أدوات لتشغيل الاختبارات ومكتبة تأكيدات (assertions) ومراقبة الدوال ومحاكاتها. وتُعد React Testing Library مكمّلاً مفيداً، إذ تتيح لنا عرض مكوّنات React ومحاكاة الأحداث على عناصر HTML.
وللاختبار الشامل (E2E)، تُعد Playwright الأداة الموصى بها، مع Cypress كبديل. وكلتاهما تتيحان أتمتة تفاعلات المستخدم ومحاكاتها في المتصفح للتأكد من أن التطبيق يتصرف كما هو مقصود.
المصادقة
بعد ذلك نهيّئ المصادقة. بوجه عام، تشمل المصادقة المفاهيم التالية:
- المصادقة (Authentication): عملية تأكيد هوية المستخدم، أي التحقق من أن من يحاول الوصول إلى تطبيق ما هو فعلاً من يدّعي أنه هو
- إدارة الجلسات (Session management): تتبع حالة مصادقة المستخدم أثناء طلبه للموارد
- التفويض (Authorization): تحديد الموارد والعمليات التي يستطيع المستخدم الوصول إليها بعد مصادقته في تطبيق ما
يمكن إعداد مصادقة المشروع بطرق كثيرة. ففي صفحة وثائق Next.js مقال كامل عن بنائها من الصفر، بما في ذلك إدارة الجلسات. لكن البدء من الصفر لن يكون لازماً دائماً، لذا يُوصى بالحلول الجاهزة، ليس أقل من أجل أمان أفضل وبساطة أكبر. وتوفر هذه المكتبات مصادقة وإدارة جلسات وتفويضاً مدمجة، إضافة إلى ميزات إضافية مثل تسجيل الدخول عبر وسائل التواصل الاجتماعي والمصادقة متعددة العوامل والتحكم في الوصول القائم على الأدوار (RBAC). ويحتفظ Next.js بقائمة من مكتبات المصادقة وإدارة الجلسات المتوافقة.
وفي تطبيقنا النموذجي، سأركز على Auth.js. وهو حل مصادقة متكامل مبني لـ Next.js لكنه يعمل أيضاً مع أطر عمل خلفية أخرى (قبل الإصدار 5 كان يسمى NextAuth ويدعم Next.js فقط). ويقلل بشكل كبير الوقت اللازم لتنفيذ مصادقة آمنة في المشروع.
من الميزات الرئيسية في Auth.js:
- دعم جاهز لمزودي المصادقة الشائعين (مثل Google وGitHub وFaceBook)
- خيار مصادقة بالبريد الإلكتروني/كلمة المرور
- إدارة جلسات شاملة
- تحكم في الوصول قائم على الأدوار
- ميزات أمنية مثل الحماية من CSRF وملفات تعريف الارتباط من نوع http-only
سأستخدم طريقتي مصادقة:
- Credentials provider – يتيح للمستخدمين تسجيل الدخول بأي بيانات اعتماد، مثل البريد الإلكتروني وكلمة المرور
- Google provider – يتيح للمستخدمين تسجيل الدخول بحساب Google
يتوفر نوعان من الجلسات لإدارة الجلسات:
- بلا حالة (Stateless) – تعيش بيانات الجلسة في ملفات تعريف الارتباط (cookies) في المتصفح. ويرافق الـ cookie كل طلب، فيستطيع الخادم التحقق منه. وهو النهج الأبسط، لكنه ربما أقل أماناً (وهذا ما سأستخدمه – رمز JWT
- قاعدة البيانات (Database) – تعيش بيانات الجلسة في قاعدة البيانات، ولا يحصل متصفح المستخدم إلا على معرّف جلسة مشفّر. وهو أكثر أماناً، لكنه قد يكون أعقد ويستهلك موارد خادم أكثر
التثبيت:
npm install next-auth@beta
الإعداد في الملف @/auth.ts:
import NextAuth, { type User } from "next-auth";
import Credentials from "next-auth/providers/credentials";
import GoogleProvider from "next-auth/providers/google";
export const { handlers, signIn, signOut, auth } = NextAuth({
session: {
strategy: "jwt",
},
providers: [
GoogleProvider,
Credentials({
credentials: {
email: {},
password: {},
},
authorize: async (credentials) => {
// ...
},
}),
],
});
بعد ذلك، يمكننا حماية المسار هكذا:
import { auth } from '@/auth';
// ...
const session = await auth();
if (!session?.user) {
return redirect('/sign-in');
}
مزيد من التفاصيل عن تثبيت Auth.js متاحة هنا.
التكامل مع قاعدة البيانات
يعني بناء تطبيق Next.js عادةً العمل مع ORM لقاعدة البيانات. ومن بين الخيارات المتاحة، يشتهر اثنان بشكل خاص: Prisma وDrizzle ORM.
اخترت Drizzle ORM. وما يميّز Drizzle أنه لا يتطلب توليد شيفرة، بخلاف Prisma. ففي Prisma تعرّف مخططاً أولاً ثم تشغّل الأمر npx prisma generate (بعد كل تغيير في ملف المخطط). وتنتج هذه الخطوة عميل Prisma (@prisma/client) وتعريفات أنواع النموذج.
أما في Drizzle، فتعريف جدول في TypeScript يعرّف في الوقت نفسه أنواعاً جاهزة للاستخدام، دون أوامر توليد شيفرة منفصلة لتشغيلها. وبالتالي، لا يحتاج تغيير المخطط في Drizzle إلى خطوة إضافية لتحديث الأنواع وعميل ORM.
ويأتي Drizzle أيضاً بدوال مساعدة مدمجة تحوّل تعريفات الجداول نفسها إلى مدققات Zod (مرة أخرى دون توليد شيفرة إضافي).
وفضلاً عن ذلك، يقدم Drizzle محوّلات (adapters) متنوعة بحسب نوع قاعدة البيانات التي يستخدمها المشروع. وتشمل الخيارات المدعومة PostgreSQL وMySQL وSQLite وNeon وSupabase، وغيرها (المزيد عن ذلك هنا). ويمكن ربط كل منها بطرق عديدة مختلفة.
أود الاتصال بـ PostgreSQL يعمل داخل حاوية Docker.
التثبيت:
npm i drizzle-orm postgres
npm i -D drizzle-kit
تهيئة المشغّل (driver):
import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import { env } from "@/env/server";
import * as schema from "./schema/index";
const queryClient = postgres(env.DATABASE_URL);
const db = drizzle({ client: queryClient, schema });
export default db;
إعداد Drizzle (drizzle.config.ts):
import { defineConfig } from "drizzle-kit";
import { env } from "@/env/server";
export default defineConfig({
out: "./src/db/migrations",
schema: "./src/db/schema/index.ts",
dialect: "postgresql",
dbCredentials: {
url: env.DATABASE_URL!,
},
});
مثال على مخطط (src/db/articles.ts):
import { relations } from "drizzle-orm";
import {
boolean,
index,
pgTable,
text,
timestamp,
uniqueIndex,
uuid,
varchar,
} from "drizzle-orm/pg-core";
import users from "./users";
const articles = pgTable(
"article",
{
id: uuid().primaryKey().defaultRandom(),
title: varchar("title", { length: 255 }),
slug: varchar("slug", { length: 255 }).notNull(),
content: text("content").notNull(),
image: varchar("image", { length: 2048 }),
isPublic: boolean("is_public").default(false),
authorId: uuid("author_id")
.notNull()
.references(() => users.id, { onDelete: "cascade" }),
createdAt: timestamp("created_at", { mode: "string" })
.notNull()
.defaultNow(),
updatedAt: timestamp("updated_at", { mode: "string" })
.notNull()
.defaultNow(),
},
(table) => [
uniqueIndex("slug_idx").on(table.slug),
index("title_idx").on(table.title),
]
);
export const articlesRelations = relations(articles, ({ one }) => ({
author: one(users, {
fields: [articles.authorId],
references: [users.id],
}),
}));
يُستورد المخطط في الملف src/db/schema/index.ts ويُربط بإعداد drizzle.config.ts. ولاستعلام قاعدة البيانات، سنضيف دالة مساعدة في الملف src/lib/actions/article.actions.ts:
"use server";
import db from "@/db";
// ...
export async function getArticleBySlug(slug: string) {
const article = await db.query.articles.findFirst({
where: eq(articles.slug, slug),
});
return article;
}
يمكن الآن استدعاء هذه الدالة في ملف الصفحة:
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { slug } = await params;
const article = await getArticleBySlug(slug);
// ...
}
حاويات Docker
لتشغيل قاعدة البيانات في حاوية Docker، تأكد من تثبيت Docker Desktop، فهو يسهّل إدارة الحاويات. يمكن بدء حاوية Docker بطرق كثيرة – مباشرة من سطر الأوامر أو من صور جاهزة مثلاً – لكن لنسلك طريقاً أكثر تنظيماً. أنشئ ملف docker-compose.yml يحتوي على جميع المعلومات المطلوبة (مثل صورة PostgreSQL والمنافذ ومتغيرات البيئة):
services:
database:
image: postgres
container_name: readium_postgres
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: readium
ports:
- 5432:5432
volumes:
- dockerreadiumdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d readium"]
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
volumes:
dockerreadiumdata:
وبعد ذلك يتلخص بدء قاعدة البيانات في تشغيل أمر واحد في الطرفية:
docker compose up
النشر
يشبه نشر تطبيق Next.js واستضافته نشر أي تطبيق آخر إلى حد كبير، ويعتمد الكثير على احتياجات المطورين واختياراتهم وعلى قرارات العمل.
وعليه، يمكن نشر Next.js:
- كخادم Node.js لدى أي مزوّد يدعم هذه البيئة
- لدى أي مزوّد يدعم حاويات Docker، بما في ذلك تنسيق الحاويات مثل Kubernetes أو مزوّد سحابي
- كتصدير ثابت (static export) (للصفحات الثابتة أو تطبيقات الصفحة الواحدة SPA)
- أو أخيراً، مكيّفاً للعمل على منصات متنوعة تدعم البنية التحتية
الخلاصة
في هذا المقال، استعرضت خطوة بخطوة بنية تطبيق full stack حديثة مبنية بـ Next.js 15 وتقنيات مثل TypeScript وServer Actions ومكوّنات الخادم والعميل وAuth.js وTailwind CSS وDrizzle ORM وPostgreSQL وDocker. وإلى جانب بيان كيفية تكامل هذه الأدوات، أوضحت كيفية إعداد بنية مشروع واضحة، والتعامل مع الحالة والأنواع، والحفاظ على تقسيم المنطق بوضوح بين الواجهة الأمامية والخلفية.
آمل أن تساعدك هذه المعرفة في بناء تطبيقات قوية وقابلة للتوسع.