انتقل إلى المحتوى

blocks.json

يوجد blocks.json في جذر القالب أو الإضافة. وهو يحدد لـ CLI مكان تثبيت الكتل والسجلات التي ينبغي البحث فيها.

المخطط

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
  }
}

الحقول

$schema

اختياري. يشير إلى مخطط JSON لإكمال المحرر التلقائي والتحقق.

directory

مطلوب. مسار نسبي من blocks.json لمكان تثبيت الكتل.

تُخصّص لكل كتلة مجلد فرعي خاص بها داخل هذا الدليل. إذا كان directory هو blockstudio وأضفت hero، فستُحفظ الملفات في blockstudio/hero/.

registries

مطلوب. كائن يربط أسماء مساحات الأسماء بمراجع السجلات.

المفتاح هو مساحة الاسم المستخدمة في أوامر CLI (npx blockstudio add ui/hero). أما القيمة، فهي إما سلسلة URL أو كائن يحتوي على url وheaders اختياري.

تنسيق السلسلة (للسجلات العامة):

JSON
{
  "registries": {
    "ui": "https://example.com/registry.json"
  }
}

تنسيق الكائن (للسجلات التي تتطلب المصادقة):

JSON
{
  "registries": {
    "private": {
      "url": "https://private.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

يمكن مزج التنسيقين في ملف الإعدادات نفسه. ويمكنك إعداد أي عدد تريده من السجلات. عند إضافة كتلة دون مساحة اسم، يبحث CLI فيها جميعًا.

المصادقة

تستخدم السجلات التي تتطلب المصادقة تنسيق الكائن مع headers. يرسل CLI هذه الترويسات مع كل طلب إلى ذلك السجل، بما في ذلك طلب جلب registry.json وتنزيل الملفات الفردية.

رمز Bearer

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

مصادقة Basic

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Basic ${REGISTRY_CREDENTIALS}"
      }
    }
  }
}

ترويسات مخصصة

يمكن إضافة أي ترويسة. يناسب ذلك مفاتيح API ومعرّفات المؤسسات أو أي قيمة يتوقعها خادم السجل:

JSON
{
  "registries": {
    "internal": {
      "url": "https://blocks.internal.company.com/registry.json",
      "headers": {
        "X-API-Key": "${BLOCKS_API_KEY}",
        "X-Org-ID": "acme"
      }
    }
  }
}

متغيرات البيئة

تدعم قيم الترويسات صيغة ${VAR_NAME} لقراءة متغيرات البيئة. وهذا يُبقي الرموز خارج نظام التحكم بالإصدارات.

يحل CLI متغيرات البيئة وقت التشغيل. إذا لم يكن أحد المتغيرات المشار إليها مضبوطًا، يخرج CLI مع خطأ يذكر المتغير المفقود والترويسة التي استُخدم فيها.

اضبط المتغير في الصدفة أو بيئة CI لديك. يقرأ CLI بيئة العملية فقط؛ ولا يحمّل ملفات .env تلقائيًا:

سطر الأوامر
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

تُمرر قيم الترويسات الثابتة (من دون ${...}) كما هي.

اكتشاف ملف الإعدادات

يتنقل CLI صعودًا من دليل العمل الحالي بحثًا عن blocks.json. وهذا يعني أنه يمكنك تشغيل الأوامر من أي دليل فرعي في مشروعك.

الكود
my-theme/
  blocks.json        <- found here
  blockstudio/
    hero/
  templates/
    page.php          <- running `npx blockstudio add` here still works

إذا لم يُعثر على blocks.json، فسيطلب منك CLI تشغيل npx blockstudio init.

مثال: قالب بسجلين

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.mycompany.com/ui/registry.json",
    "internal": "https://blocks.mycompany.com/internal/registry.json"
  }
}

مثال: إضافة بدليل مخصص

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "src/blocks",
  "registries": {
    "starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
  }
}