تطوير Next.js كامل المكدس مع Cursor

تطور Next.js ليصبح إطار عمل React كامل المكدس مع App Router، ومكونات الخادم، ومسارات API المدمجة. تسرع ميزات الذكاء الاصطناعي في Cursor كل جانب من جوانب تطوير Next.js -- من إنشاء الهياكل إلى النشر على Vercel. يغطي هذا الدليل سير العمل العملي لبناء تطبيقات Next.js للإنتاج.

إعداد المشروع مع Cursor

إنشاء مشروع جديد

ابدأ بطلب من Cursor إعداد مشروع Next.js حديث:

# Ask Cursor: "Generate the command to create a Next.js 14+ app with TypeScript and Tailwind"
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

بعد الإنشاء، اطلب من Cursor تكوين الملفات الأساسية:

// app/layout.tsx
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import './globals.css';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'My Next.js App',
  description: 'Built with Cursor AI',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
}

تلميح

حدد دائماً "App Router" عند طلب أكواد Next.js من Cursor. يختلف Pages Router عن الأنماط، وقد يستخدم Cursor النمط الأقدم افتراضياً.

هيكل المجلدات

اطلب من Cursor إنشاء هيكل مجلد قابل للتوسع:

my-app/
├── app/
│   ├── api/              # مسارات API
│   ├── (auth)/           # مجموعات المسارات (بدون جزء URL)
│   ├── dashboard/        # صفحات لوحة التحكم
│   ├── layout.tsx        # التخطيط الجذري
│   ├── page.tsx          # الصفحة الرئيسية
│   ├── loading.tsx       # واجهة التحميل
│   └── error.tsx         # حدود الأخطاء
├── components/
│   ├── ui/               # مكونات واجهة مستخدم قابلة لإعادة الاستخدام
│   └── forms/            # مكونات النماذج
├── lib/
│   ├── db.ts             # اتصال قاعدة البيانات
│   ├── auth.ts           # مساعدو المصادقة
│   └── utils.ts          # الدوال المساعدة
├── types/
│   └── index.ts          # أنواع TypeScript العامة
├── hooks/
│   └── useUser.ts        # خطافات React المخصصة
└── public/
    └── images/           # الأصول الثابتة

أنماط App Router

مكونات الخادم

يستخدم App Router مكونات الخادم افتراضياً. استخدم Cursor لإنشاء أكواد جانب الخادم بكفاءة:

// app/users/page.tsx - Server Component
import { Suspense } from 'react';
import { UserList } from '@/components/UserList';
import { UserListSkeleton } from '@/components/UserListSkeleton';

// This runs on the server
async function getUsers() {
  const res = await fetch('https://api.example.com/users', {
    next: { revalidate: 60 } // Revalidate every 60 seconds
  });
  if (!res.ok) throw new Error('Failed to fetch users');
  return res.json();
}

export default async function UsersPage() {
  const usersPromise = getUsers();

  return (
    <main className="p-8">
      <h1 className="text-2xl font-bold mb-4">Users</h1>
      <Suspense fallback={<UserListSkeleton />}>
        <UserList usersPromise={usersPromise} />
      </Suspense>
    </main>
  );
}

معلومات

اطلب من Cursor "إنشاء مكون خادم يجلب البيانات مع معالجة الأخطاء وحالات التحميل المناسبة" لأفضل النتائج.

مكونات العميل

عندما تحتاج إلى التفاعلية، ضع علامة على المكونات بـ 'use client':

// components/SearchForm.tsx
'use client';

import { useState } from 'react';
import { useRouter } from 'next/navigation';

export function SearchForm() {
  const [query, setQuery] = useState('');
  const router = useRouter();

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    router.push(`/search?q=${encodeURIComponent(query)}`);
  };

  return (
    <form onSubmit={handleSubmit} className="flex gap-2">
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
        className="border rounded px-3 py-2"
      />
      <button type="submit" className="bg-blue-500 text-white px-4 py-2 rounded">
        Search
      </button>
    </form>
  );
}

مجموعات المسارات والتخطيطات

استخدم مجموعات المسارات لتنظيم الصفحات المرتبطة دون التأثير على URL:

app/
├── (marketing)/
│   ├── layout.tsx        # تخطيط التسويق (تنقل مختلف، تذييل)
│   ├── page.tsx          # / (الصفحة الرئيسية)
│   ├── about/
│   │   └── page.tsx      # /about
│   └── pricing/
│       └── page.tsx      # /pricing
├── (dashboard)/
│   ├── layout.tsx        # تخطيط لوحة التحكم (شريط جانبي، فحص المصادقة)
│   ├── dashboard/
│   │   └── page.tsx      # /dashboard
│   └── settings/
│       └── page.tsx      # /dashboard/settings
└── api/
    └── ...

مسارات API

نقاط نهاية RESTful API

أنشئ مسارات API آمنة للأنواع مع Cursor:

// app/api/users/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

export async function GET() {
  try {
    const users = await db.user.findMany();
    return NextResponse.json({ users });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to fetch users' },
      { status: 500 }
    );
  }
}

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const validated = createUserSchema.parse(body);

    const user = await db.user.create({
      data: validated,
    });

    return NextResponse.json({ user }, { status: 201 });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Invalid input', details: error.errors },
        { status: 400 }
      );
    }
    return NextResponse.json(
      { error: 'Failed to create user' },
      { status: 500 }
    );
  }
}

معالجات المسارات الديناميكية

// app/api/users/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(
  request: NextRequest,
  { params }: { params: { id: string } }
) {
  const user = await db.user.findUnique({
    where: { id: params.id },
  });

  if (!user) {
    return NextResponse.json(
      { error: 'User not found' },
      { status: 404 }
    );
  }

  return NextResponse.json({ user });
}

المصادقة

تنفيذ المصادقة باستخدام NextAuth.js

اطلب من Cursor إعداد المصادقة:

// app/api/auth/[...nextauth]/route.ts
import NextAuth from 'next-auth';
import GoogleProvider from 'next-auth/providers/google';
import { PrismaAdapter } from '@auth/prisma-adapter';
import { db } from '@/lib/db';

const handler = NextAuth({
  adapter: PrismaAdapter(db),
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
  callbacks: {
    session({ session, user }) {
      if (session.user) {
        session.user.id = user.id;
      }
      return session;
    },
  },
});

export { handler as GET, handler as POST };

حماية المسارات

// middleware.ts
import { withAuth } from 'next-auth/middleware';

export default withAuth({
  pages: {
    signIn: '/login',
  },
});

export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
};

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

إعداد Prisma

// lib/db.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const db = globalForPrisma.prisma ?? new PrismaClient();

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = db;

إجراءات الخادم

استخدم إجراءات الخادم لإرسال النماذج والتعديلات:

// app/actions.ts
'use server';

import { revalidatePath } from 'next/cache';
import { z } from 'zod';

const createPostSchema = z.object({
  title: z.string().min(1),
  content: z.string().min(1),
});

export async function createPost(formData: FormData) {
  const data = Object.fromEntries(formData);
  const validated = createPostSchema.parse(data);

  const post = await db.post.create({
    data: validated,
  });

  revalidatePath('/posts');
  return { success: true, post };
}

// app/posts/new/page.tsx
import { createPost } from '@/app/actions';

export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" placeholder="Title" required />
      <textarea name="content" placeholder="Content" required />
      <button type="submit">Create Post</button>
    </form>
  );
}

warning

تحقق دائماً من المدخلات في إجراءات الخادم. لا تثق أبداً بالبيانات المرسلة من العميل.

إنشاء الأكواد بمساعدة الذكاء الاصطناعي

إنشاء الصفحات

صف ما تحتاجه، ويقوم Cursor بإنشاء الصفحة الكاملة:

Prompt: "أنشئ صفحة Next.js على /products تعرض شبكة من بطاقات المنتجات. يجب أن تعرض كل بطاقة صورة واسم وسعر وزر 'أضف إلى السلة'. استخدم مكونات الخادم لجلب البيانات وTailwind للتنسيق."

إنشاء مسارات API

Prompt: "أنشئ واجهة برمجة تطبيقات CRUD لنموذج Todo مع Prisma. أدرج GET all، GET by id، POST create، PATCH update، ونقاط نهاية DELETE. أضف تحقق Zod ومعالجة أخطاء مناسبة."

إنشاء المكونات

Prompt: "ولّد مكون DataTable قابل لإعادة الاستخدام مع الفرز والتصفية والتصفح. استخدم TypeScript واقبل نوع صف عام."

النشر على Vercel

قائمة ما قبل النشر

Check	Command
فحص الأنواع	npx tsc --noEmit
Lint	npm run lint
البناء محلياً	npm run build
الاختبار	npm test

متغيرات البيئة

قم بتكوين متغيرات البيئة للإنتاج في Vercel:

# .env.local (development)
DATABASE_URL="postgresql://..."
NEXTAUTH_SECRET="your-secret"
NEXTAUTH_URL="http://localhost:3000"
GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."

تكوين النشر

// vercel.json
{
  "buildCommand": "prisma generate && next build",
  "installCommand": "npm install",
  "framework": "nextjs",
  "regions": ["iad1"]
}

تلميح

اطلب من Cursor "إنشاء دليل نشر كامل لتطبيق Next.js هذا على Vercel مع إعداد البيئة" للحصول على إرشادات خاصة بالمشروع.

تحسين الأداء

تحسين الصور

import Image from 'next/image';

// Automatic optimization
<Image
  src="/hero.jpg"
  alt="Hero"
  width={1200}
  height={600}
  priority
  className="rounded-lg"
/>

البث والتعليق

import { Suspense } from 'react';
import { ProductList } from '@/components/ProductList';
import { ProductListSkeleton } from '@/components/ProductListSkeleton';

export default function ShopPage() {
  return (
    <div>
      <h1>Shop</h1>
      {/* العرض الفوري */}
      <CategoryNav />

      {/* البث عند الجاهزية */}
      <Suspense fallback={<ProductListSkeleton />}>
        <ProductList />
      </Suspense>
    </div>
  );
}

استراتيجيات التخزين المؤقت

Strategy	Use Case	Implementation
ثابت	محتوى لا يتغير	export const dynamic = 'force-static'
مع إعادة التحقق	محتوى شبه ثابت	next: { revalidate: 60 }
ديناميكي	محتوى خاص بالمستخدم	export const dynamic = 'force-dynamic'
عند الطلب	محتوى يتغير عند الأحداث	revalidatePath() / revalidateTag()

ملخص

يتضمن بناء تطبيقات Next.js كاملة المكدس مع Cursor:

• استخدام الذكاء الاصطناعي لإنشاء المشاريع بأنماط حديثة
• الاستفادة من مكونات الخادم لجلب البيانات بكفاءة
• إنشاء مسارات API آمنة للأنواع وإجراءات الخادم
• تنفيذ المصادقة باستخدام NextAuth.js
• النشر بسلاسة على Vercel مع التكوين المناسب
• تحسين الأداء بالبث والتعليق والتخزين المؤقت

يعني فهم Cursor لاتفاقيات Next.js أنه يمكنك وصف الميزات بلغة طبيعية وتلقي أكواد جاهزة للإنتاج تتبع أفضل ممارسات الإطار.

---

Last updated: July 2025. Next.js features depend on the installed version. App Router requires Next.js 13+.