كيفية بناء مكتبة CSS باستخدام Vite.js

Updated يونيو 8, 2026 6 min read

Aldawsari

دقائق القراءة: 6

لماذا قد تحتاج إلى بناء مكتبة CSS خاصة بك؟

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

كما أن مكتبة CSS المشتركة تمنح تطبيقاتك واجهات أكثر اتساقاً، وهو أمر مهم للحفاظ على الهوية البصرية للمنتج أو العلامة التجارية. ومع نمو المشروع، يصبح هذا الاتساق عاملاً أساسياً في تسريع التطوير وتسهيل التوسع، وقد تكون المكتبة جزءاً من Design System أكبر وأكثر تنظيماً.

في هذا الدليل، سنركز على بناء مكتبة CSS نفسها باستخدام Vite.js، وليس على تصميم مكوناتها بصرياً. والهدف النهائي هو إنتاج مكتبة مشابهة في فكرتها لـ Bootstrap، بحيث تستخدم فئات CSS جاهزة لتنسيق عناصر HTML مباشرة.

بناء مكتبة CSS باستخدام Vite.js لتطوير واجهات أمامية قابلة لإعادة الاستخدام

ما الذي سنبنيه في هذا الدليل؟

إنشاء Library Build باستخدام Vite بدلاً من بناء تطبيق ويب تقليدي.
التعامل مع Static Assets المستخدمة داخل ملفات CSS.
استخدام SASS بدلاً من CSS التقليدية.
تغليف المكتبة ونشرها كحزمة عبر npm.

إعداد المشروع باستخدام Vite.js

سنبدأ بإنشاء مشروع جديد باستخدام Vite، ثم نحوله لاحقاً إلى مكتبة CSS قابلة للاستخدام في مشاريع أخرى. يتميز Vite بأنه أداة تطوير وبناء سريعة تجعل تجربة العمل على الواجهات الأمامية أكثر سلاسة.

شغّل الأمر التالي:

npm init @vitejs/app

أدخل اسم المشروع.
اختر الإطار المناسب. في هذا المثال سنختار vanilla لأن التركيز هنا على CSS فقط.

بعد إنشاء المشروع، ستجد أن نقطة الدخول الأساسية هي ملف index.html. سنستخدمه لاختبار ما نبنيه أثناء التطوير، لكنه لن يكون جزءاً من الحزمة النهائية الخاصة بالمكتبة.

تنظيف الكود الابتدائي وتحديث ملفات المشروع

الخطوة الأولى هي التخلص من الكود الافتراضي الذي يولده Vite، ثم استبداله بعناصر بسيطة تساعدنا على اختبار المكتبة.

تحديث ملف HTML

استبدل محتوى index.html بالكود التالي:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite App</title>
  </head>
  <body>
    <div id="app">
      <div class="logo"></div>
      <button class="tomato">Click me</button>
    </div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

تحديث ملف main.ts

اذهب إلى مجلد src واحذف محتوى ملف main.ts مع الإبقاء على سطر استيراد ملف الأنماط فقط.

إضافة التنسيقات الأساسية

داخل ملف style.css أضف الكود التالي:

.tomato {
  background-color: tomato;
}

.logo {
  background: url(/logo.png) no-repeat;
  height: 300px;
}

بعد ذلك، انسخ ملف logo.png إلى المجلد الجذر للمشروع. ويمكنك استخدام أي صورة أخرى بشرط تعديل قيمة الارتفاع height بما يناسب أبعادها.

اختبار المشروع محلياً قبل بناء المكتبة

قبل إنشاء الحزمة النهائية، من الأفضل التأكد من أن كل شيء يعمل بشكل صحيح أثناء التطوير المحلي.

انتقل إلى المجلد الجذر للمشروع.
ثبت الاعتمادات:

npm install

شغّل خادم التطوير المحلي:

npm run dev

بعد ذلك افتح المشروع في المتصفح عبر العنوان المحلي الذي يعرضه Vite، وغالباً يكون:

http://localhost:3000

إذا ظهرت الصورة والزر بتنسيقهما الصحيح، يمكنك الانتقال إلى خطوة البناء.

إنشاء أول Build للمشروع

نفذ الأمر التالي:

npm run build

سينتج عن ذلك مجلد dist يحتوي على الملفات المبنية.

شكل مجلد dist بعد أول عملية build لمشروع Vite

لكن هذه النتيجة تشبه بناء تطبيق ويب كامل جاهز للاستضافة، بينما ما نحتاجه هنا هو مكتبة يمكن استيرادها داخل مشاريع أخرى. لذلك نحتاج إلى تعديل إعدادات Vite.

تهيئة Vite لبناء مكتبة CSS

في المجلد الجذر للمشروع، أنشئ ملفاً جديداً باسم config.vite.js وأضف إليه الإعدادات التالية:

import { defineConfig } from "vite";
import path from "path";

module.exports = defineConfig({
  build: {
    lib: {
      entry: path.resolve(__dirname, "src/main.ts"),
      name: "MyCssLib",
    },
  },
});

الآن أعد تشغيل البناء:

npm run build

ستلاحظ أن بنية مجلد dist أصبحت مختلفة.

بنية مجلد dist بعد تهيئة Vite ليبني مكتبة بدلاً من تطبيق ويب

في هذا الشكل الجديد، لم يعد هناك ملف HTML ضمن الحزمة، وبقيت الأنماط ضمن ملف CSS. لكن قد تلاحظ أن الصورة المشار إليها في CSS لم تعد موجودة كملف مستقل داخل الناتج.

السبب أن Vite قام بتحويل الأصل الثابت إلى base64 data URL وضمّنه مباشرة داخل ملف CSS. هذه الطريقة تعمل جيداً في المشاريع الصغيرة، لكنها قد تسبب تضخماً في حجم ملف CSS إذا كانت المكتبة تحتوي على عدد كبير من الصور أو الأيقونات.

مثال على تحويل مسار الصورة داخل CSS إلى base64 بواسطة Vite

كيفية التعامل مع Static Assets داخل مكتبة CSS

لتجنب تضمين الأصول داخل CSS بصيغة base64، يوفر Vite طريقة أسهل وأكثر تنظيماً للتعامل مع الملفات الثابتة.

أنشئ مجلداً جديداً باسم public في جذر المشروع.
انقل ملف logo.png إلى هذا المجلد.

بعد هذه الخطوة، سيستمر التطبيق المحلي في التعرف على الصورة كما كان سابقاً. تأكد من ذلك عبر تشغيل المشروع محلياً.

ثم شغّل أمر البناء مرة أخرى:

npm run build

ستصبح بنية مجلد dist مشابهة لما يلي:

مجلد dist بعد نقل الأصول إلى public للحفاظ على الملفات الثابتة

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

ومن الأفضل تنظيم الأصول داخل مجلد فرعي مثل public/assets، ثم تحديث المسار في ملف CSS من:

/logo.png

إلى:

/assets/logo.png

استخدام SASS بدلاً من CSS التقليدية

يعتمد كثير من المطورين على SASS لأنه يوفر مرونة أكبر في كتابة الأنماط، مثل المتغيرات والتنظيم الأفضل وتقسيم الملفات. الجميل هنا أن Vite يدعم SASS بشكل مباشر.

تثبيت SASS

npm install sass

إعادة تسمية ملف الأنماط

داخل مجلد src غيّر اسم الملف من style.css إلى style.scss.

إضافة كود SASS

يمكنك الآن استخدام ميزات SASS، مثل المتغيرات:

$color: tomato;

.tomato {
  background-color: $color;
}

بعد ذلك، حدّث ملف main.ts ليشير إلى style.scss بدلاً من style.css.

ثم نفذ البناء من جديد:

npm run build

إذا فتحت ملف style.css الناتج داخل dist، ستجد أن Vite حول كود SASS إلى CSS صالح للاستخدام:

.tomato{background-color:tomato}

تغليف مكتبة CSS باستخدام npm

بعد تجهيز ملفات المكتبة داخل dist، تأتي خطوة تغليفها على شكل حزمة يمكن تثبيتها في أي مشروع آخر عبر npm.

تحديث package.json

افتح ملف package.json وأضف خاصية files. هذه الخاصية تحدد الملفات التي يجب تضمينها عند تثبيت الحزمة كاعتماد داخل مشروع آخر.

بما أننا نريد تضمين ملف CSS الناتج فقط، أضف ما يشبه التالي:

"files": ["dist/style.css"]

إنشاء الحزمة

بعد حفظ التعديلات، شغّل الأمر التالي:

npm pack

سينشئ ذلك ملفاً مضغوطاً بصيغة .tgz، مثل:

vite-css-lib-0.0.0.tgz

كيفية استخدام الحزمة في مشروع جديد

الآن يمكنك تجربة المكتبة داخل مشروع Front-end آخر.

أنشئ مشروعاً جديداً، ويمكنك استخدام Vite أيضاً لهذه المهمة.
ثبت الحزمة التي أنشأتها محلياً بالأمر التالي:

npm install <path-to-lib>/vite-css-lib-0.0.0.tgz

في ملف main.js، استورد ملف CSS:

import 'node_modules/vite-css-lib/dist/style.css'

في ملف index.html، أضف زراً يستخدم الفئة tomato:

<button class="tomato">Submit</button>

عند تشغيل التطبيق، يجب أن يظهر الزر بخلفية بلون tomato، ما يعني أن المكتبة تعمل كما ينبغي.

أفكار مهمة لتحسين المكتبة مستقبلاً

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

تصدير ملفات SASS الأصلية بدلاً من تصدير CSS المترجم فقط، حتى تتمكن المشاريع المستهلكة للمكتبة من الاستفادة من المتغيرات وميزات SASS مباشرة.
استخدام Vite/Rollup Plugin لتخصيص آلية التصدير أو إدارة الملفات بشكل أفضل.
تنظيف package.json لتجنب تضمين سكربتات أو اعتمادات غير ضرورية داخل الحزمة النهائية.
إضافة ملف JavaScript وسيط يقوم بتصدير ملف CSS تلقائياً، لتسهيل الاستيراد دون الحاجة إلى كتابة المسار الكامل داخل node_modules.
تنظيم المكتبة ضمن Design System يشمل الألوان والمسافات والطباعة والمكونات القابلة لإعادة الاستخدام.

أفضل الممارسات عند بناء مكتبة CSS قابلة للتوسع

الممارسة	الفائدة
تنظيم الأصول داخل public/assets	يسهّل إدارة الصور والخطوط والأيقونات
استخدام SASS	يحسن قابلية الصيانة ويوفر متغيرات وMixins
تقليل الملفات المنشورة في npm	يجعل الحزمة أخف وأكثر احترافية
الحفاظ على أسماء الفئات واضحة	يسهّل استخدام المكتبة داخل المشاريع المختلفة
اختبار المكتبة في مشروع منفصل	يكشف مشاكل الاستيراد والتوافق مبكراً

الخلاصة التقنية

يُعد Vite.js خياراً ممتازاً لبناء مكتبة CSS خفيفة وسريعة، خاصة عندما تحتاج إلى سير عمل حديث يدعم SASS وإدارة الأصول والتغليف عبر npm بدون تعقيد كبير. ومن الناحية العملية، فإن أهم نقطة في هذا المسار ليست مجرد إنشاء ملف أنماط قابل للاستيراد، بل بناء مكتبة منظمة وسهلة التوسع وقابلة للاستخدام في مشاريع متعددة دون التضحية بالأداء أو قابلية الصيانة. إذا أضفت لاحقاً نظام مكونات واضحاً، وهيكلة ملفات مدروسة، وآلية نشر نظيفة، فستتحول المكتبة من تجربة تقنية بسيطة إلى أصل حقيقي يدعم منتجاتك على المدى الطويل.