الـ Bootstrap و (Vite)

الدليل الرسمي حول كيفية تضمين وحزم الـ CSS والـ JavaScript الخاص بـ Bootstrap في مشروعك باستخدام Vite.

في هذه الصفحة

هل تريد الانتقال إلى النهاية مباشرة؟ قم بتنزيل الكود المصدري والعرض التوضيحي الشغال لهذا الدليل من مستودع twbs/examples. يمكنك أيضاً فتح المثال في StackBlitz للتعديل المباشر.

ما هو Vite؟

Vite هو أداة بناء واجهات أمامية حديثة مصممة للسرعة والبساطة. يوفر تجربة تطوير فعالة وانسيابية، خاصة لأطر عمل الـ JavaScript الحديثة.

التثبيت (Setup)

نحن نقوم ببناء مشروع Vite باستخدام الـ Bootstrap من الصفر، لذا هناك بعض المتطلبات المسبقة والخطوات الأولية قبل أن نبدأ فعلياً. يتطلب هذا الدليل تثبيت Node.js وبعض المعرفة بالـ terminal.

إنشاء مجلد المشروع وإعداد npm. سنقوم بإنشاء مجلد my-project وتهيئة npm باستخدام الوسيط -y لتجنب طرح جميع الأسئلة التفاعلية علينا.
```
mkdir my-project && cd my-project
npm init -y
```
تثبيت Vite. على عكس دليل Webpack الخاص بنا، يوجد هنا تبعية واحدة فقط لأداة البناء. نستخدم --save-dev للإشارة إلى أن هذه التبعية مخصصة للاستخدام أثناء التطوير فقط وليس للإنتاج.
```
npm i --save-dev vite
```
تثبيت Bootstrap. الآن يمكننا تثبيت الـ Bootstrap. سنقوم أيضاً بتثبيت Popper لأن القوائم المنسدلة (dropdowns) والنوافذ المنبثقة (popovers) وتلميحات الأدوات (tooltips) تعتمد عليه في تحديد مواقعها. إذا كنت لا تخطط لاستخدام تلك المكونات، يمكنك حذف Popper هنا.
```
npm i --save bootstrap @popperjs/core
```
تثبيت تبعية إضافية. بالإضافة إلى Vite و Bootstrap، نحتاج إلى تبعية أخرى (Sass) لاستيراد وحزم الـ CSS الخاص بـ Bootstrap بشكل صحيح.
```
npm i --save-dev sass
```

الآن بعد أن قمنا بتثبيت وإعداد جميع التبعيات اللازمة، يمكننا البدء في إنشاء ملفات المشروع واستيراد الـ Bootstrap.

هيكل المشروع

لقد قمنا بالفعل بإنشاء مجلد my-project وتهيئة npm. الآن سنقوم أيضاً بإنشاء مجلد src، وورقة أنماط (stylesheet)، وملف JavaScript لاستكمال هيكل المشروع. قم بتشغيل ما يلي من my-project، أو قم بإنشاء هيكل المجلدات والملفات الموضح أدناه يدوياً.

mkdir {src,src/js,src/scss}
touch src/index.html src/js/main.js src/scss/styles.scss vite.config.js

عندما تنتهي، يجب أن يبدو مشروعك الكامل بهذا الشكل:

my-project/
├── src/
│   ├── js/
│   │   └── main.js
│   └── scss/
│   |   └── styles.scss
|   └── index.html
├── package-lock.json
├── package.json
└── vite.config.js

في هذه المرحلة، كل شيء في مكانه الصحيح، ولكن Vite لن يعمل لأننا لم نقم بملء ملف vite.config.js بعد.

تهيئة Vite

بعد تثبيت التبعيات وتجهيز مجلد المشروع لبدء البرمجة، يمكننا الآن تهيئة Vite وتشغيل مشروعنا محلياً.

افتح vite.config.js في المحرر الخاص بك. بما أنه فارغ، سنحتاج إلى إضافة بعض إعدادات النموذج الأساسية إليه حتى نتمكن من بدء الخادم الخاص بنا. يخبر هذا الجزء من الإعداد Vite أين يبحث عن الـ JavaScript الخاص بمشروعنا وكيف يجب أن يتصرف خادم التطوير (السحب من مجلد src مع التحديث المباشر hot reload).
```
import { resolve } from 'path'

export default {
  root: resolve(__dirname, 'src'),
  build: {
    outDir: '../dist'
  },
  server: {
    port: 8080
  },
  // Optional: Silence Sass deprecation warnings. See note below.
  css: {
     preprocessorOptions: {
        scss: {
          silenceDeprecations: [
            'import',
            'mixed-decls',
            'color-functions',
            'global-builtin',
          ],
        },
     },
  },
}
```
ملاحظة: تظهر تحذيرات استبعاد (deprecation) الـ Sass عند تجميع ملفات Sass المصدرية باستخدام أحدث إصدارات Dart Sass. هذا لا يمنع التجميع أو استخدام الـ Bootstrap. نحن نعمل على حل طويل الأمد، ولكن في هذه الأثناء يمكن تجاهل هذه التنبيهات.

بعد ذلك نقوم بملء src/index.html. هذه هي صفحة HTML التي سيقوم Vite بتحميلها في المتصفح لاستخدام الـ CSS والـ JS المحزومين اللذين سنضيفهما في الخطوات اللاحقة.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Bootstrap w/ Vite</title>
    <script type="module" src="./js/main.js"></script>
  </head>
  <body>
    <div class="container py-4 px-3 mx-auto">
      <h1>Hello, Bootstrap and Vite!</h1>
      <button class="btn btn-primary">Primary button</button>
    </div>
  </body>
</html>

لقد قمنا بتضمين القليل من تنسيقات الـ Bootstrap هنا باستخدام div class="container" و <button> حتى نرى متى يتم تحميل الـ CSS الخاص بـ Bootstrap بواسطة Vite.

الآن نحتاج إلى نص برمجي (script) في npm لتشغيل Vite. افتح package.json وأضف نص start الموضح أدناه (يجب أن يكون لديك بالفعل نص الاختبار test). سنستخدم هذا النص لبدء خادم تطوير Vite المحلي الخاص بنا.
```
{
  // ...
  "scripts": {
    "start": "vite",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  // ...
}
```
وأخيراً، يمكننا تشغيل Vite. من مجلد my-project في الـ terminal الخاص بك، قم بتشغيل نص npm الذي تمت إضافته حديثاً:
```
npm start
```

في القسم التالي والأخير من هذا الدليل، سنقوم باستيراد جميع ملفات الـ CSS والـ JavaScript الخاصة بـ Bootstrap.

استيراد Bootstrap

استيراد الـ CSS الخاص بـ Bootstrap. أضف ما يلي إلى src/scss/styles.scss لاستيراد جميع ملفات Sass المصدرية الخاصة بـ Bootstrap.
```
// Import all of Bootstrap’s CSS
@import "bootstrap/scss/bootstrap";
```
يمكنك أيضاً استيراد أوراق الأنماط (stylesheets) الخاصة بنا بشكل فردي إذا كنت ترغب في ذلك. اقرأ مستندات استيراد Sass لمزيد من التفاصيل.
بعد ذلك نقوم بتحميل الـ CSS واستيراد الـ JavaScript الخاص بـ Bootstrap. أضف ما يلي إلى src/js/main.js لتحميل الـ CSS واستيراد جميع ملفات JS الخاصة بـ Bootstrap. سيتم استيراد Popper تلقائياً من خلال Bootstrap.
```
// Import our custom CSS
import '../scss/styles.scss'

// Import all of Bootstrap’s JS
import * as bootstrap from 'bootstrap'
```
يمكنك أيضاً استيراد الإضافات (plugins) الخاصة بـ JavaScript بشكل فردي حسب الحاجة لتقليل أحجام الحزم:
```
import Alert from 'bootstrap/js/dist/alert';

// or, specify which plugins you need:
import { Tooltip, Toast, Popover } from 'bootstrap';
```
اقرأ مستندات JavaScript الخاصة بنا لمزيد من المعلومات حول كيفية استخدام إضافات (plugins) الـ Bootstrap.
وهكذا انتهيت! 🎉 مع تحميل الـ Sass والـ JS المصدرية لـ Bootstrap بالكامل، يجب أن يبدو خادم التطوير المحلي الخاص بك الآن بهذا الشكل:

الآن يمكنك البدء في إضافة أي مكونات Bootstrap تريد استخدامها. تأكد من إلقاء نظرة على مشروع Vite التجريبي الكامل لمعرفة كيفية تضمين Sass مخصص إضافي وتحسين عملية البناء عن طريق استيراد الأجزاء التي تحتاجها فقط من الـ CSS والـ JS الخاص بـ Bootstrap.

هل لاحظت شيئاً خاطئاً أو قديماً هنا؟ يرجى فتح مشكلة على GitHub. هل تحتاج إلى مساعدة في استكشاف الأخطاء وإصلاحها؟ ابحث أو ابدأ نقاشاً على GitHub.