خطأ في Astro 5 Glob Loader في الـ Monorepos

نجحت عملية بناء Astro الخاصة بك. صفر أخطاء. صفر تحذيرات. ولكن المحتوى مفقود.

واجهت هذه المشكلة مؤخرًا في pnpm monorepo. كنت أستخدم Astro 5 content collections لإضافة آراء تحريرية (editorial takes) إلى صفحاتي. محليًا، كان كل شيء يعمل بشكل مثالي. أما في خط أنابيب CI الخاص بي، فقد تم عرض الصفحات بمحتوى فارغ.

المشكلة تكمن في كيفية قيام الـ glob loader بفك مسارات الملفات (resolving paths).

المشكلة

يقوم Astro glob loader بفك مسارات القاعدة النسبية (relative base paths) بناءً على process.cwd(). هو لا يستخدم موقع ملف الإعدادات الخاص بك.

في الـ monorepo، غالبًا ما يقوم الـ CI بتشغيل عملية البناء من جذر مساحة العمل (workspace root). أما محليًا، فمن المحتمل أنك تقوم بتشغيل البناء من دليل التطبيق (app directory).

  • محليًا: الـ cwd هو apps/oss-alternatives. المسار ./content يعمل.
  • في الـ CI: الـ cwd هو جذر المستودع (repository root). المسار ./content غير موجود.

لا يطلق Astro خطأً عندما لا يجد ملفات. بل ببساطة يعيد مجموعة (collection) فارغة. وبذلك تقوم بنشر موقع ببيانات مفقودة دون أن تدرك ذلك أبدًا.

الحل

توقف عن استخدام السلاسل النصية النسبية (relative strings) للمسارات. استخدم import.meta.url لربط مساراتك بملف الإعدادات بدلاً من دليل العمل (working directory).

استخدم هذا النمط:

import { fileURLToPath } from "node:url";

const TAKES_DIR = fileURLToPath(
  new URL("./content/per-alternative-takes", import.meta.url)
);

يضمن هذا أن يكون المسار صحيحًا دائمًا، بغض النظر عن المكان الذي تقوم بتشغيل البناء منه.

تجنب تصادم المعرفات (ID Collisions)

يستخدم الـ glob loader حقل slug في الـ frontmatter الخاص بك كمعرف (ID) بشكل افتراضي. إذا قام مستخدم بإضافة حقل slug ، فقد يؤدي ذلك إلى تعطل عمليات البحث عن البيانات. استخدم generateId لفرض استخدام اسم الملف كمعرف أساسي.

دروس لمطوري الـ Monorepo

  • قم بتشغيل اختبارات الدخان (smoke tests) من جذر مساحة العمل محليًا. إذا كنت تختبر فقط من مجلد التطبيق، فستفوتك أخطاء المسارات.
  • أضف فحوصات سلامة للمجموعات (collection health checks). في بيئة التطوير الخاصة بك، قم بإطلاق خطأ إذا أعادت مجموعة حيوية صفرًا من العناصر.
  • استخدم فك المسارات المطلقة (absolute path resolution) لكل مرجع ملف في ملفات الإعداد الخاصة بك.
  • أضف فحصًا لما بعد النشر (post-deploy check) للتحقق من وجود المحتوى الرئيسي في ملف HTML المباشر.

لا تثق أبدًا في الصمت. فعملية البناء الناجحة لا تعني دائمًا عملية نشر ناجحة.

Source: https://dev.to/morinaga/what-i-learned-about-astro-5-glob-loader-path-resolution-in-a-pnpm-monorepo-2ed4