استخدام أدوات حزم الوحدات مع Firebase

يمكن أن تنفّذ حِزم وحدات JavaScript العديد من المهام، ولكن من أكثر ميزاتها فائدةً هي إمكانية إضافة مكتبات خارجية واستخدامها في قاعدة الرموز البرمجية. تقرأ أدوات تجميع الوحدات مسارات الاستيراد في الرمز وتجمع (تحزم) الرمز الخاص بتطبيقك مع رمز المكتبة الذي تم استيراده.

بدءًا من الإصدار 9 والإصدارات الأحدث، تم تحسين واجهة برمجة التطبيقات النموذجية في JavaScript من Firebase لتتوافق مع ميزات التحسين في أدوات تجميع الوحدات النمطية، وذلك بهدف تقليل كمية رموز Firebase المضمّنة في الإصدار النهائي.

import { initializeApp } from 'firebase/app';
import { getAuth, onAuthStateChanged, getRedirectResult } from 'firebase/auth';

const firebaseApp = initializeApp({ /* config */ });
const auth = getAuth(firebaseApp);
onAuthStateChanged(auth, user => { /* check status */ });

/**
 * getRedirectResult is unused and should not be included in the code base.
 * In addition, there are many other functions within firebase/auth that are
 * not imported and therefore should not be included as well.
 */

تُعرف عملية إزالة الرموز غير المستخدَمة من المكتبة باسم "إزالة الرموز غير المستخدَمة". ستستغرق إزالة هذا الرمز يدويًا وقتًا طويلاً جدًا، كما أنّها ستكون عرضة للأخطاء، ولكن يمكن لحِزم الوحدات أن تنفّذ هذه الإزالة تلقائيًا.

تتوفّر العديد من أدوات تجميع الوحدات العالية الجودة في منظومة JavaScript المتكاملة. يركّز هذا الدليل على استخدام Firebase مع webpack وRollup وesbuild.

البدء

يتطلّب هذا الدليل تثبيت npm في بيئة التطوير، ويتم استخدام npm لتثبيت العناصر التابعة (المكتبات) وإدارتها. لتثبيت npm، عليك تثبيت Node.js، الذي يتضمّن npm تلقائيًا.

يتم إعداد معظم المطوّرين بشكل صحيح بعد تثبيت Node.js. ومع ذلك، يواجه العديد من المطوّرين مشاكل شائعة عند إعداد بيئة التطوير. إذا واجهت أي أخطاء، تأكَّد من أنّ بيئتك تتضمّن واجهة سطر الأوامر npm ومن أنّ لديك الأذونات المناسبة حتى لا تضطر إلى تثبيت الحِزم بصفتك مشرفًا باستخدام الأمر sudo.

ملف package.json وتثبيت Firebase

بعد تثبيت npm، عليك إنشاء ملف package.json في الجذر الخاص بمشروعك المحلي. أنشئ هذا الملف باستخدام أمر npm التالي:

npm init

سيتم توجيهك من خلال معالج لتوفير المعلومات المطلوبة. بعد إنشاء الملف، سيظهر على النحو التالي:

{
  "name": "your-package-name",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {

  }
}

هذا الملف مسؤول عن العديد من المهام المختلفة. هذا الملف مهم جدًا ويجب التعرّف عليه إذا أردت معرفة المزيد عن تجميع الوحدات النمطية وإنشاء رمز JavaScript بشكل عام. العنصر المهم في هذا الدليل هو الكائن "dependencies". سيحتوي هذا العنصر على زوج مفتاح/قيمة خاص بالمكتبة التي ثبّتها والإصدار الذي تستخدمه.

تتم إضافة التبعيات من خلال الأمر npm install أو npm i.

npm i firebase

عند تشغيل npm i firebase، ستعدّل عملية التثبيت package.json لإدراج Firebase كعنصر تابع:

  "dependencies": {
    "firebase": "^9.0.0"
  },

المفتاح هو اسم المكتبة والقيمة هي الإصدار الذي سيتم استخدامه. قيمة الإصدار مرنة ويمكن أن تقبل نطاقًا من القيم. ويُعرف ذلك باسم الإصدار الدلالي أو semver. لمزيد من المعلومات عن semver، اطّلِع على دليل npm حول تحديد الإصدارات الدلالية.

مجلدات المصدر مقابل مجلدات الإنشاء

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

من الإعدادات الشائعة في قواعد الرموز تخزين رمز المصدر في مجلد باسم src، وتخزين الرمز البرمجي الذي تم إنشاؤه في مجلد باسم dist.

- src
 |_ index.js
 |_ animations.js
 |_ datalist.js


- dist
 |_ bundle.js

في بنية الملف المثال أعلاه، ضع في اعتبارك أنّ index.js يستورد كلاً من animations.js وdatalist.js. عندما يعالج مجمّع الوحدات النمطية رمز المصدر، سينتج ملف bundle.js في المجلد dist. يمثّل bundle.js مجموعة من الملفات في المجلد src وأي مكتبات يتم استيرادها.

في حال استخدام أنظمة التحكّم في المصدر مثل Git، من الشائع تجاهل المجلد dist عند تخزين هذا الرمز في المستودع الرئيسي.

نقاط الدخول

تتضمّن جميع حزم الوحدات النمطية مفهوم نقطة الدخول. يمكنك التفكير في تطبيقك على أنّه شجرة من الملفات. يستورد أحد الملفات الرمز من ملف آخر وهكذا. وهذا يعني أنّ ملفًا واحدًا سيكون جذر الشجرة. يُعرف هذا الملف باسم نقطة الدخول.

دعنا نراجع مثال بنية الملف السابق.

- src
 |_ index.js
 |_ animations.js
 |_ datalist.js


- dist
 |_ bundle.js

// src/index.js
import { animate } from './animations';
import { createList } from './datalist';

// This is not real code, but for example purposes only
const theList = createList('users/123/tasks');
theList.addEventListener('loaded', event => {
  animate(theList);
});

يُعدّ الملف src/index.js نقطة الدخول لأنّه يبدأ عمليات استيراد جميع الرموز البرمجية اللازمة للتطبيق. يتم استخدام ملف نقطة الدخول هذا من خلال أدوات تجميع الوحدات لبدء عملية التجميع.

استخدام Firebase مع webpack

لا يلزم إجراء أي إعدادات معيّنة لتطبيقات Firebase وwebpack. يتناول هذا القسم إعدادًا عامًا لحزمة الويب.

الخطوة الأولى هي تثبيت webpack من npm كإحدى تبعيات التطوير.

npm i webpack webpack-cli -D

أنشئ ملفًا في جذر مشروعك المحلي باسم webpack.config.js وأضِف الرمز التالي.

const path = require('path');

module.exports = {
  // The entry point file described above
  entry: './src/index.js',
  // The location of the build folder described above
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  // Optional and for development only. This provides the ability to
  // map the built code back to the original source format when debugging.
  devtool: 'eval-source-map',
};

بعد ذلك، تأكَّد من تثبيت Firebase كعنصر تابع.

npm i firebase

بعد ذلك، عليك إعداد Firebase في قاعدة الرموز البرمجية. يستورد الرمز التالي Firebase ويهيئه في ملف نقطة دخول، ويستخدم Firestore Lite لتحميل مستند "مدينة".

// src/index.js
import { initializeApp } from 'firebase/app';
import { getFirestore, doc, getDoc } from 'firebase/firestore/lite';

const firebaseApp = initializeApp({ /* config */ });
const db = getFirestore(firebaseApp);

async function loadCity(name) {
  const cityDoc = doc(db, `cities/${name}`);
  const snapshot = await getDoc(cityDoc);
  return {
    id: snapshot.id,
    ...snapshot.data(),
  };
}

الخطوة التالية هي إضافة نص برمجي npm لتشغيل عملية إنشاء webpack. افتح ملف package.json وأضِف زوج المفتاح/القيمة التالي إلى العنصر "scripts".

  "scripts": {
    "build": "webpack --mode=development"
  },

لتشغيل webpack وإنشاء مجلد الإصدار، شغِّل الأمر التالي.

npm run build

أخيرًا، تحقَّق من dist مجلد الإنشاء. يجب أن يحتوي على ملف باسم bundle.js يتضمّن رمز التطبيق المجمّع ورمز التبعية.

لمزيد من المعلومات حول تحسين إصدار webpack المخصّص للإنتاج، راجِع المستندات الرسمية حول إعدادات "الوضع".

استخدام Firebase مع Rollup

لا يلزم إجراء أيّ إعدادات معيّنة لتطبيقات Firebase وRollup. يتناول هذا القسم إعدادات عامة لعملية التجميع.

تتمثل الخطوة الأولى في تثبيت Rollup ومكوّن إضافي يُستخدم لربط عمليات الاستيراد بالحِزم التابعة المثبّتة باستخدام npm.

npm i rollup @rollup/plugin-node-resolve -D

أنشِئ ملفًا في جذر مشروعك المحلي باسم rollup.config.js وأضِف الرمز التالي.

import { nodeResolve } from '@rollup/plugin-node-resolve';

export default {
  // the entry point file described above
  input: 'src/index.js',
  // the output for the build folder described above
  output: {
    file: 'dist/bundle.js',
    // Optional and for development only. This provides the ability to
    // map the built code back to the original source format when debugging.
    sourcemap: 'inline',
    // Configure Rollup to convert your module code to a scoped function
    // that "immediate invokes". See the Rollup documentation for more
    // information: https://rollupjs.org/guide/en/#outputformat
    format: 'iife'
  },
  // Add the plugin to map import paths to dependencies
  // installed with npm
  plugins: [nodeResolve()]
};

بعد ذلك، عليك إعداد Firebase في قاعدة الرموز البرمجية. يستورد الرمز التالي Firebase ويهيئه في ملف نقطة دخول، ويستخدم Firestore Lite لتحميل مستند "مدينة".

// src/index.js
import { initializeApp } from 'firebase/app';
import { getFirestore, doc, getDoc } from 'firebase/firestore/lite';

const firebaseApp = initializeApp({ /* config */ });
const db = getFirestore(firebaseApp);

async function loadCity(name) {
  const cityDoc = doc(db, `cities/${name}`);
  const snapshot = await getDoc(cityDoc);
  return {
    id: snapshot.id,
    ...snapshot.data(),
  };
}

الخطوة التالية هي إضافة نص برمجي npm لتشغيل عملية إنشاء الحزمة. افتح ملف package.json وأضِف زوج المفتاح/القيمة التالي إلى العنصر "scripts".

  "scripts": {
    "build": "rollup -c rollup.config.js"
  },

لتشغيل عملية التجميع وإنشاء مجلد الإصدار، شغِّل الأمر التالي.

npm run build

أخيرًا، تحقَّق من dist مجلد الإنشاء. يجب أن يحتوي على ملف باسم bundle.js يتضمّن رمز التطبيق المجمّع ورمز التبعية.

لمزيد من المعلومات حول تحسين إصدار Rollup المخصّص للإنتاج، يمكنك الاطّلاع على المستندات الرسمية حول المكوّنات الإضافية لإصدارات الإنتاج.

استخدام Firebase مع esbuild

لا يلزم إجراء أي إعدادات معيّنة لتطبيقات Firebase وesbuild. يتناول هذا القسم إعدادات esbuild العامة.

الخطوة الأولى هي تثبيت esbuild كإضافة تطوير.

npm i esbuild -D

أنشئ ملفًا في جذر مشروعك المحلي باسم esbuild.config.js وأضِف الرمز التالي.

require('esbuild').build({
  // the entry point file described above
  entryPoints: ['src/index.js'],
  // the build folder location described above
  outfile: 'dist/bundle.js',
  bundle: true,
  // Replace with the browser versions you need to target
  target: ['chrome60', 'firefox60', 'safari11', 'edge20'],
  // Optional and for development only. This provides the ability to
  // map the built code back to the original source format when debugging.
  sourcemap: 'inline',
}).catch(() => process.exit(1))

بعد ذلك، عليك إعداد Firebase في قاعدة الرموز البرمجية. يستورد الرمز التالي Firebase ويهيئه في ملف نقطة دخول، ويستخدم Firestore Lite لتحميل مستند "مدينة".

// src/index.js
import { initializeApp } from 'firebase/app';
import { getFirestore, doc, getDoc } from 'firebase/firestore/lite';

const firebaseApp = initializeApp({ /* config */ });
const db = getFirestore(firebaseApp);

async function loadCity(name) {
  const cityDoc = doc(db, `cities/${name}`);
  const snapshot = await getDoc(cityDoc);
  return {
    id: snapshot.id,
    ...snapshot.data(),
  };
}

الخطوة التالية هي إضافة نص برمجي npm لتشغيل esbuild. افتح الملف package.json وأضِف زوج المفتاح والقيمة التالي إلى العنصر "scripts".

  "scripts": {
    "build": "node ./esbuild.config.js"
  },

أخيرًا، تحقَّق من dist مجلد الإنشاء. يجب أن يحتوي على ملف باسم bundle.js يتضمّن رمز التطبيق المجمّع ورمز التبعية.

لمزيد من المعلومات حول تحسين esbuild لمرحلة الإنتاج، يُرجى الاطّلاع على مستنداتهم الرسمية حول التصغير وعمليات التحسين الأخرى.