Μετάβαση στο περιεχόμενο

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

Υποχρεωτικό. Ένα αντικείμενο που αντιστοιχίζει ονόματα namespace σε αναφορές μητρώων.

Το κλειδί είναι το namespace που χρησιμοποιείται στις εντολές 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}"
      }
    }
  }
}

Μπορείτε να συνδυάσετε και τις δύο μορφές στην ίδια ρύθμιση και να ορίσετε όσα μητρώα θέλετε. Όταν προσθέτετε μπλοκ χωρίς namespace, το CLI τα αναζητά σε όλα.

Έλεγχος ταυτότητας

Τα μητρώα που απαιτούν έλεγχο ταυτότητας χρησιμοποιούν τη μορφή αντικειμένου με headers. Το CLI στέλνει αυτές τις κεφαλίδες σε κάθε αίτημα προς το συγκεκριμένο μητρώο, συμπεριλαμβανομένης τόσο της ανάκτησης του registry.json όσο και των λήψεων μεμονωμένων αρχείων.

Διακριτικό Bearer

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

Βασικός έλεγχος ταυτότητας

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"
  }
}