إدارة Monorepo في Cursor: Turborepo و Nx ومساحات عمل pnpm

تتيح لك Monorepos الاحتفاظ بحزم أو تطبيقات متعددة في مستودع واحد، ومشاركة الكود والتكوين والأدوات. يجعل Cursor، وهو محرر IDE مدعوم بالذكاء الاصطناعي، إدارة monorepo أسهل بشكل كبير من خلال فهم العلاقات بين الحزم، وتوليد تكوينات خط الأنابيب، وإعادة هيكلة واجهات API المشتركة بأمان. يغطي هذا الدليل Turborepo و Nx ومساحات عمل pnpm، مع تقنيات عملية لإدارة التبعيات بمساعدة الذكاء الاصطناعي وإعادة الهيكلة عبر الحزم.

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

• Cursor (يُنصح بأحدث إصدار) كمحرر IDE الخاص بك
• Node.js 18 أو أعلى
• pnpm مثبت عالميًا (npm install -g pnpm)
• معرفة أساسية بمديري الحزم ومساحات العمل

تلميح

تجعل الطرفية المدمجة في Cursor ودعم مساحة العمل متعددة الجذور الأمر مثاليًا لـ monorepos. افتح جذر المستودع في Cursor حتى يتمكن الذكاء الاصطناعي من رؤية كل حزمة في وقت واحد. هذا يعطي المحرر سياقًا كاملاً لإعادة الهيكلة عبر الحزم وتحليل التبعيات.

اختيار أداة Monorepo

تهيمن ثلاث أدوات على مشهد monorepos لـ JavaScript و TypeScript. لكل منها نقاط قوة مختلفة:

الأداة	الأفضل لـ	نقطة القوة الرئيسية
مساحات عمل pnpm	Monorepos صغيرة إلى متوسطة	تثبيتات سريعة وفعالة من حيث القرص
Turborepo	Monorepos تركز على التطبيقات	تخزين مؤقت بسيط للمهام وتشغيل متوازي
Nx	Monorepos كبيرة بكثرة الإضافات	توليد كود قوي ورسم بياني للتبعيات

اطلب من ذكاء Cursor الاصطناعي التوصية بأداة لحالتك:

لدي monorepo مع تطبيقين Next.js ومكتبة مكونات React مشتركة
و3 حزم أدوات مساعدة. هل أستخدم Turborepo أم Nx؟ قارنهما.

يشرح Cursor المقايضات ويُنشئ تكوينًا مبدئيًا للأداة التي اخترتها.

إعداد مساحات عمل pnpm في Cursor

مساحات عمل pnpm هي أساس معظم monorepos الحديثة بسبب سرعتها وكفاءة القرص ذاتية الربط. يساعدك Cursor في تعريف مساحة العمل وتمهيد الحزم الأولى.

إنشاء جذر مساحة العمل

افتح مجلدًا جديدًا في Cursor واطلب من الذكاء الاصطناعي إنشاء مساحة عمل pnpm:

أنشئ monorepo لمساحة عمل pnpm مع:
- package.json جذر مع تكوين مساحة عمل pnpm
- pnpm-workspace.yaml يسرد apps/* و packages/*
- حزمة تكوين TypeScript مشتركة
- .npmrc مع إعدادات cache المشتركة

يُنشئ Cursor الملفات الجذرية:

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

// package.json
{
  "name": "cursor-monorepo",
  "private": true,
  "scripts": {
    "dev": "pnpm -r --parallel run dev",
    "build": "pnpm -r run build",
    "lint": "pnpm -r run lint",
    "test": "pnpm -r run test"
  },
  "devDependencies": {
    "typescript": "^5.4.0"
  }
}

# .npmrc
shared-cache-max-age=86400
auto-install-peers=true
strict-peer-dependencies=false

إنشاء الحزم الأولى

اطلب من Cursor إنشاء حزمة UI مشتركة وتطبيق ويب يستهلكها:

أنشئ مكتبة مكونات React في packages/ui وتطبيق Next.js في apps/web.
يجب أن يعتمد تطبيق الويب على حزمة ui باستخدام بروتوكول workspace:*.

يُنشئ Cursor هيكل الحزمة:

monorepo/
  apps/
    web/
      package.json
      src/
        app/page.tsx
  packages/
    ui/
      package.json
      src/
        index.ts
        Button.tsx
  pnpm-workspace.yaml
  package.json

ملف packages/ui/package.json:

{
  "name": "@cursor-monorepo/ui",
  "version": "0.1.0",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "scripts": {
    "lint": "eslint .",
    "build": "tsc"
  },
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

يشير apps/web/package.json إلى الحزمة المشتركة باستخدام بروتوكول مساحة العمل:

{
  "name": "@cursor-monorepo/web",
  "version": "0.1.0",
  "dependencies": {
    "@cursor-monorepo/ui": "workspace:*",
    "next": "^14.0.0",
    "react": "^18.0.0"
  }
}

ثبّت كل شيء من الجذر باستخدام طرفية Cursor:

pnpm install

يستخدم pnpm روابط صلبة للتبعيات، لذا التثبيت سريع وفعال من حيث القرص.

warning

استخدم دائمًا بروتوكول workspace:* (أو workspace:^) عند الإشارة إلى الحزم الداخلية. إذا قمت بتثبيت رقم إصدار مثل 1.0.0، يحاول pnpm جلب الحزمة من السجل بدلاً من حل الحزمة المحلية، مما يسبب أخطاء "الحزمة غير موجودة" مربكة أثناء التثبيت.

تكامل Turborepo في Cursor

يضيف Turborepo تخزينًا مؤقتًا وتنفيذًا متوازيًا للمهام فوق مساحات عمل pnpm. يُنشئ Cursor تكوين خط الأنابيب ويساعدك في ضبطه.

إضافة Turborepo إلى مساحة عمل موجودة

اطلب من Cursor إضافة Turborepo إلى monorepo الخاص بك:

أضف Turborepo إلى مساحة عمل pnpm الخاصة بي. أنشئ turbo.json مع
خطوط أنابيب build و dev و lint و test. كوّن تبعيات البناء
والتخزين المؤقت.

يثبّت Cursor التبعية ويُنشئ turbo.json:

pnpm add -Dw turbo

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "inputs": [
        "src/**",
        "package.json",
        "tsconfig.json"
      ]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["src/**", "test/**", "package.json"]
    }
  }
}

تخبر التوجيه dependsOn: ["^build"] Turborepo ببناء تبعيات الحزمة قبل بناء الحزمة نفسها، وهو أمر بالغ الأهمية لـ monorepos حيث تعتمد التطبيقات على مكتبات مشتركة.

تشغيل المهام مع Turbo

شغّل المهام عبر monorepo بأكمله من طرفية Cursor:

# بناء جميع الحزم بترتيب طوبولوجي
pnpm turbo run build

# تشغيل خوادم التطوير بالتوازي
pnpm turbo run dev --parallel

# التصفية لحزمة واحدة والمُعتمِدة عليها
pnpm turbo run build --filter=@cursor-monorepo/web...

تعني اللاحقة ... "هذه الحزمة وكل ما يعتمد عليها،" وهو أمر مفيد لتحليل التأثير عندما تغير مكتبة مشتركة.

تلميح

استخدم علم --filter مع بادئة ^ لتشغيل مهمة لحزمة وتبعياتها فقط. على سبيل المثال، pnpm turbo run build --filter=^@cursor-monorepo/web يبني فقط الحزم التي يحتاجها تطبيق الويب، متخطيًا العمل غير ذي الصلة. هذا لا يُقدر بثمن لدورات التغذية الراجعة المحلية السريعة.

تكوين التخزين المؤقت عن بُعد

يتيح التخزين المؤقت عن بُعد لفريقك مشاركة نتائج البناء. اطلب من Cursor إعداد التخزين المؤقت عن بُعد لـ Vercel:

كوّن التخزين المؤقت عن بُعد لـ Turborepo لـ monorepo الخاص بي.
أنشئ مثال .nenv واشرح كيفية ربط التخزين المؤقت.

يشرح Cursor الخطوات:

npx turbo login
npx turbo link

أضف تلميح بيئة إلى turbo.json حتى تتضمن مفاتيح التخزين المؤقت المتغيرات الصحيحة:

{
  "globalEnv": ["NODE_ENV", "CI"]
}

تكامل Nx في Cursor

Nx أداة monorepo أقوى مع مولدات الكود ورسوم بيانية للتبعيات ودعم الإضافات للعديد من الأطر. يساعدك Cursor في التمهيد وتوسيع مشاريع Nx.

إنشاء مساحة عمل Nx

اطلب من Cursor إنشاء مساحة عمل Nx:

أنشئ monorepo Nx متكامل مع:
- تطبيق React باسم storefront
- تطبيق Node API باسم api
- مكتبة أنواع مشتركة
- pnpm كمدير حزم

يشغّل Cursor التمهيد ويشرح النتيجة:

npx create-nx-workspace@latest cursor-nx --preset=apps --packageManager=pnpm

الهيكل الناتج:

cursor-nx/
  apps/
    storefront/
    api/
  libs/
    types/
  nx.json
  project.json

توليد الكود بإضافات Nx

توفر إضافات Nx مولدات لإنشاء متسق. اطلب من Cursor توليد مكتبة مكونات React:

ولّد مكتبة React باسم ui مع buildable true وتكوين
Storybook باستخدام إضافة @nx/react.

npx nx g @nx/react:library ui --buildable --storybook --directory=libs/ui

تصور الرسم البياني للتبعيات

يأتي Nx مع عارض رسوم بيانية. شغّله من طرفية Cursor:

npx nx graph

يفتح هذا رسمًا بيانيًا تفاعليًا في متصفحك يُظهر كيف تعتمد الحزم على بعضها البعض. يمكن لذكاء Cursor الاصطناعي أيضًا وصف الرسم البياني في نص إذا طلبت:

اسرد جميع الحزم التي تعتمد على libs/types وتنكسر إذا أعدت
تسمية export الافتراضي الخاص بها.

يقرأ Cursor تكوين مساحة العمل ويعيد تحليل التأثير، وهو أمر أساسي قبل إعادة هيكلة الكود المشترك.

warning

تستخدم مساحات عمل Nx المتكاملة تعيين المسارات في tsconfig.base.json للاستيرادات. إذا أضفت مكتبة جديدة، يجب تحديث تعيين paths وإلا فلن يتمكن TypeScript من حل الاستيراد. يمكن لذكاء Cursor الاصطناعي اكتشاف تعيينات المسارات المفقودة واقتراح الإصلاح عندما ترى أخطاء "Cannot find module".

إدارة التبعيات بمساعدة الذكاء الاصطناعي

الحفاظ على اتساق التبعيات عبر monorepo هو أحد أصعب مهام الصيانة. يتفوق ذكاء Cursor الاصطناعي في ذلك.

تدقيق عدم تطابق الإصدارات

اطلب من Cursor العثور على عدم تطابق التبعيات:

امسح جميع ملفات package.json في monorepo الخاص بي وأبلغ عن
أي تبعيات لها إصدارات غير متسقة عبر الحزم. اقترح إصدارًا
مثبتًا واحدًا لكل منها.

يقرأ Cursor كل package.json، ويسرد عدم التطابق، ويمكنه إنشاء نص لمحاذاتها:

# محاذاة react إلى 18.2.0 في كل مكان
pnpm -r exec pnpm add [email protected] [email protected]

اكتشاف التبعيات غير المستخدمة

يمكن لـ Cursor اكتشاف الحزم المُعلنة في package.json ولكنها غير مُستوردة أبدًا. اطلب:

ابحث عن التبعيات غير المستخدمة في حزمة apps/web من خلال
التحقق من الاستيرادات عبر جميع ملفات المصدر.

يُبلغ Cursor عن الإدخالات غير المستخدمة ويقترح أمر الإزالة:

pnpm --filter @cursor-monorepo/web remove unused-package-name

إدارة تبعيات التطوير المشتركة

ارفع أدوات التطوير المشتركة (ESLint، Prettier، TypeScript) إلى جذر مساحة العمل لتجنب انحراف الإصدار. يُنشئ Cursor حزمة تكوين مشتركة:

أنشئ حزمة packages/config تصدّر تكوينات ESLint و TypeScript
و Prettier مشتركة حتى تتمكن الحزم الأخرى من توسيعها.

// packages/config/package.json
{
  "name": "@cursor-monorepo/config",
  "version": "0.1.0",
  "files": ["eslint", "tsconfig", "prettier"],
  "devDependencies": {
    "eslint": "^8.57.0",
    "prettier": "^3.2.0"
  }
}

// packages/config/eslint/base.js
module.exports = {
  extends: ['next', 'prettier'],
  rules: {
    'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
    'no-console': ['warn', { allow: ['warn', 'error'] }],
  },
};

توسع الحزم الأخرى التكوين المشترك:

{
  "eslintConfig": { "extends": "@cursor-monorepo/config/eslint" }
}

تلميح

استخدم ميزة catalog الخاصة بـ pnpm (أو Renovate) لتركيز أرقام الإصدار في مكان واحد. اطلب من Cursor: "أعد كتالوج pnpm لجميع إصدارات التبعيات المشتركة،" وسيُنشئ كتلة الكتالوج في pnpm-workspace.yaml بحيث ينتشر تحديث إصدار واحد في كل مكان تلقائيًا.

إعادة الهيكلة عبر الحزم مع Cursor

تؤثر إعادة هيكلة واجهة API مشتركة على كل مستهلك. تتيح فهرسة قاعدة الكود في Cursor للذكاء الاصطناعي تتبع الاستخدامات عبر monorepo بأكمله، مما يجعل إعادة الهيكلة الكبيرة آمنة.

إعادة تسمية export مشترك

لنفترض أنك تريد إعادة تسمية مكوّن Button إلى ActionButton في packages/ui. اطلب من Agent في Cursor:

أعد تسمية مكوّن Button إلى ActionButton عبر monorepo بأكمله.
حدّث export والنوع وجميع الاستيرادات وقصص Storybook.
شغّل البناء للتحقق من عدم كسر شيء.

ينفذ Cursor التحرير متعدد الملفات في تمريرة واحدة:

// packages/ui/src/ActionButton.tsx
import React from 'react';

export interface ActionButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export const ActionButton = ({ label, onClick, variant = 'primary' }: ActionButtonProps) => (
  <button className={`btn btn-${variant}`} onClick={onClick}>
    {label}
  </button>
);

// packages/ui/src/index.ts
export { ActionButton } from './ActionButton';
export type { ActionButtonProps } from './ActionButton';

// apps/web/src/app/page.tsx
import { ActionButton } from '@cursor-monorepo/ui';

export default function Home() {
  return <ActionButton label="Get Started" onClick={() => alert('hi')} />;
}

استخراج أداة مساعدة مشتركة

عندما تجد منطقًا مكررًا عبر الحزم، اطلب من Cursor استخراجه:

استخرج منطق تنسيق التاريخ المكرر في apps/web و apps/api
إلى حزمة مشتركة جديدة تسمى @cursor-monorepo/format.
حدّث جميع مواقع الاستدعاء للاستيراد من الحزمة الجديدة.

يُنشئ Cursor الحزمة، وينقل الكود، ويحدّث الاستيرادات، ويشغّل البناء المتأثر لتأكيد النجاح.

warning

بعد إعادة هيكلة عبر الحزم، شغّل دائمًا مجموعة الاختبار الكاملة وفحص الأنواع لمساحة العمل بأكملها. استيراد مفقود واحد قد يُجمّع في عزلة لكنه يفشل عند تجميع الحزم. شغّل pnpm -r run build && pnpm -r run test من الجذر لاكتشاف هذه المشاكل مبكرًا.

تكوين مساحة العمل والأدوات

الأدوات المتسقة عبر الحزم تحافظ على صحة monorepo. يمكن لـ Cursor إنشاء تكوينات مشتركة لـ TypeScript و ESLint و CI.

تكوين TypeScript المشترك

أنشئ tsconfig أساسي مشترك في packages/config/tsconfig/base.json
مع الوضع الصارم وأسماء المسارات المستعارة وإعدادات lib الحديثة.

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "moduleResolution": "bundler",
    "module": "ESNext",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

توسعه كل حزمة:

{
  "extends": "@cursor-monorepo/config/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

خط أنابيب CI مع GitHub Actions

اطلب من Cursor إنشاء خط أنابيب CI يستفيد من التخزين المؤقت لـ Turborepo:

أنشئ سير عمل GitHub Actions يقوم بـ:
- تثبيت pnpm و Node
- استعادة ذاكرة التخزين المؤقت لـ pnpm store
- تشغيل turbo run lint build test مع التخزين المؤقت
- تشغيل المهام المتأثرة فقط على pull requests

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v3
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - uses: actions/cache@v4
        with:
          path: .turbo
          key: turbo-${{ runner.os }}-${{ github.sha }}
          restore-keys: turbo-${{ runner.os }}-
      - run: pnpm turbo run lint build test

ملخص أفضل الممارسات

ضع هذه المبادئ في الاعتبار عند إدارة monorepo في Cursor:

• افتح جذر مساحة العمل حتى يرى Cursor كل حزمة للسياق عبر الحزم.
• استخدم بروتوكول مساحة العمل (workspace:*) للإشارات إلى الحزم الداخلية.
• ارفع أدوات التطوير المشتركة إلى حزمة تكوين لتجنب انحراف الإصدار.
• استفد من تخزين المهام المؤقت مع Turborepo أو Nx للحفاظ على CI سريعًا.
• شغّل تحليل التأثير قبل إعادة هيكلة واجهات API المشتركة.
• ركز الإصدارات مع كتالوجات pnpm أو Renovate.

من خلال الجمع بين أداة monorepo قوية وفهم قاعدة الكود المدعوم بالذكاء الاصطناعي في Cursor، يمكنك إعادة هيكلة الكود المشترك بثقة، والحفاظ على اتساق التبعيات، وتسليم أدوات متسقة عبر العديد من الحزم. صِف نيتك بوضوح، ودع Cursor يتعامل مع الكود المتكرر والتحرير عبر الملفات، وراجع الفروقات المُنشأة قبل الالتزام.