1. ما هو tsup ولماذا تحتاجه؟

tsup هو أداة تجميع (bundler) حديثة وسريعة وسهلة الاستخدام لـ TypeScript، مبنية على esbuild. مهمته الأساسية هي تجميع مكتبة TypeScript الخاصة بك في ملف واحد أو عدة ملفات، جاهزة للنشر على npm أو للاستخدام في مشاريع أخرى. على عكس الإعدادات المعقدة لـ Webpack أو Rollup، يقدم tsup إعدادات جاهزة "من الصندوق" بدون أي تهيئة في معظم الحالات.

لماذا تحتاج tsup؟ عند تطوير مكتبات TypeScript، تواجه عدة تحديات: تحتاج إلى ترجمة TypeScript إلى JavaScript، وإنشاء ملفات تعريف الأنواع (.d.ts)، ودمج ملفات متعددة في ملف واحد (bundle) لسهولة الاستخدام، ودعم تنسيقات وحدات مختلفة (CommonJS, ESM). يحل tsup كل هذه المهام بأمر واحد. فهو يعالج الاستيرادات تلقائيًا، ويصغر حجم الكود (اختياريًا)، وينشئ خرائط المصدر (source maps)، ويدعم tree-shaking.

tsup مثالي لـ: إنشاء حزم npm، ومكتبات الأدوات المساعدة، ومكونات React/Vue، وعملاء API، وأي مشاريع أخرى تحتاج إلى بناء سريع وبسيط لـ TypeScript. بفضل استخدام esbuild، يعمل tsup أسرع بمقدار 10-100 مرة من أدوات التجميع التقليدية، وهو ما يظهر بوضوح في المشاريع الكبيرة.

2. التثبيت

يتم تثبيت tsup عبر npm أو yarn كاعتماد تطوير (dev-dependency):

# npm
npm install --save-dev tsup

# yarn
yarn add --dev tsup

# pnpm
pnpm add --save-dev tsup

بعد التثبيت، يمكنك تشغيل tsup عبر npx أو إضافة سكريبت في package.json.

3. البداية السريعة — مثال عملي بسيط

لننشئ مكتبة بسيطة ونقوم بتجميعها باستخدام tsup.

الخطوة 1: أنشئ ملف src/index.ts:

// src/index.ts
export function greet(name: string): string {
    return `مرحبًا، ${name}! أهلاً بك في tsup.`;
}

export function add(a: number, b: number): number {
    return a + b;
}

الخطوة 2: أنشئ ملف الإعدادات tsup.config.ts (أو استخدم وسائط سطر الأوامر):

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
    entry: ['src/index.ts'],        // نقطة الدخول
    format: ['cjs', 'esm'],         // تنسيقات الإخراج
    dts: true,                      // إنشاء ملفات .d.ts
    splitting: false,               // عدم التقسيم إلى أجزاء
    sourcemap: true,                // إنشاء خرائط المصدر
    clean: true,                    // تنظيف مجلد dist قبل البناء
});

الخطوة 3: أضف سكريبت في package.json:

{
    "scripts": {
        "build": "tsup"
    }
}

الخطوة 4: قم بتشغيل البناء:

npm run build

ستظهر النتائج في مجلد dist/:

dist/
├── index.js          (CommonJS)
├── index.mjs         (ESM)
├── index.d.ts        (تعريفات الأنواع)
├── index.d.mts       (تعريفات لـ ESM)
└── index.js.map      (خريطة المصدر)

4. الخصائص الأساسية

في tsup، لا توجد كلاسيكيات بالمعنى التقليدي. واجهة API الرئيسية هي دالة defineConfig وكائن الإعدادات. دعنا نستعرض 8 خيارات إعدادات رئيسية.

4.1. entry

التوقيع: entry: string | string[] | Record

يحدد نقطة أو نقاط الدخول للمشروع. يمكن أن يكون مسارًا واحدًا أو مصفوفة من المسارات أو كائنًا لتعيين أسماء مخرجات مخصصة.

// مسار واحد
entry: ['src/index.ts']

// مسارات متعددة
entry: ['src/index.ts', 'src/cli.ts']

// أسماء مخرجات مخصصة
entry: {
    'my-lib': 'src/index.ts',
    'cli': 'src/cli.ts',
}

يتم إنشاء ملف مخرج لكل نقطة دخول. إذا كنت تستخدم كائنًا، فستكون أسماء المفاتيح هي أسماء الملفات الناتجة.