registry.json
Το registry.json είναι αρχείο JSON που φιλοξενείται σε URL. Παραθέτει όλα τα διαθέσιμα μπλοκ ενός μητρώου, τα μεταδεδομένα τους, τις εξαρτήσεις και τα manifests αρχείων.
Σχήμα
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "ui",
"description": "Core UI blocks for Blockstudio projects.",
"baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
"blocks": [
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with accessible keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": [
"block.json",
"index.php",
"style.scss"
]
}
]
}
Πεδία ανώτατου επιπέδου
name
Υποχρεωτικό. Το αναγνωριστικό του μητρώου. Το CLI το επικυρώνει, αλλά δεν το εμφανίζει: οι εντολές και η έξοδος χρησιμοποιούν το κλειδί που επέλεξε ο χρήστης για το μητρώο στο blocks.json.
description
Προαιρετικό. Σύντομη περιγραφή του περιεχομένου αυτού του μητρώου.
baseUrl
Υποχρεωτικό. Το βασικό URL για τη λήψη αρχείων μπλοκ. Πρέπει να είναι έγκυρο URL.
Τα αρχεία λαμβάνονται συνδυάζοντας το βασικό URL, το όνομα του μπλοκ και τη διαδρομή του αρχείου: {baseUrl}/{block.name}/{file}.
Για παράδειγμα, αν το baseUrl έχει οριστεί σε
https://raw.githubusercontent.com/acme/blocks/main/blocks και ένα μπλοκ
ονομάζεται tabs και περιέχει το αρχείο index.php, το CLI λαμβάνει:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
Πεδία μπλοκ
name
Υποχρεωτικό. Το όνομα του φακέλου του μπλοκ. Αυτό είναι το αναγνωριστικό που χρησιμοποιείται στις εντολές CLI και γίνεται το όνομα του φακέλου στον δίσκο.
title
Προαιρετικό. Αναγνώσιμο από άνθρωπο όνομα που εμφανίζεται στην έξοδο των list και search.
description
Προαιρετικό. Περιγραφή μίας γραμμής που εμφανίζεται στα αποτελέσματα του search.
category
Προαιρετικό. Ετικέτα ομαδοποίησης για την έξοδο του list.
type
Προαιρετικό. Μία από τις τιμές blockstudio, create-block ή wordpress.
Είναι μόνο ενημερωτικό. Το CLI δεν αλλάζει τη συμπεριφορά ανάλογα με τον τύπο του μπλοκ. Κατεβάζει και αντιγράφει πάντα τα αρχεία που παρατίθενται στο files.
dependencies
Προαιρετικό. Πίνακας με τα ονόματα άλλων μπλοκ στο ίδιο μητρώο, τα οποία πρέπει να εγκατασταθούν μαζί με αυτό το μπλοκ.
Όταν ένας χρήστης προσθέτει μπλοκ με εξαρτήσεις, το CLI επιλύει ολόκληρο το δέντρο εξαρτήσεων και εγκαθιστά τα πάντα με τη σωστή σειρά. Οι κυκλικές εξαρτήσεις εντοπίζονται και απορρίπτονται.
Οι εξαρτήσεις πρέπει να υπάρχουν στο ίδιο μητρώο. Δεν υποστηρίζονται εξαρτήσεις μεταξύ μητρώων.
files
Υποχρεωτικό. Πίνακας διαδρομών αρχείων σχετικών με τον φάκελο του μπλοκ. Απαιτείται τουλάχιστον ένα αρχείο.
Αυτά είναι τα ακριβή αρχεία που κατεβάζει το CLI και γράφει στον δίσκο. Οι διαδρομές μπορούν να περιλαμβάνουν υποκαταλόγους:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
Επίλυση διαδρομών αρχείων
Για κάθε αρχείο στο manifest ενός μπλοκ, το CLI κατασκευάζει ένα URL λήψης:
{baseUrl}/{block.name}/{file}
Και το γράφει στη θέση:
{directory}/{block.name}/{file}
Η δομή καταλόγων μέσα στον φάκελο του μπλοκ διατηρείται. Αν μια διαδρομή αρχείου περιέχει υποκαταλόγους, αυτοί δημιουργούνται αυτόματα.
Τα αρχεία λαμβάνονται πάντα από το baseUrl μέσα στο registry.json και όχι από θέση σχετική με το URL του μητρώου στο blocks.json.
Επικύρωση
Το CLI επικυρώνει το registry.json έναντι σχήματος Zod σε κάθε ανάκτηση. Τα μη έγκυρα μητρώα προκαλούν σαφή μηνύματα σφάλματος με τα συγκεκριμένα πεδία που απέτυχαν στην επικύρωση.
Τα υποχρεωτικά πεδία που λείπουν, οι κενές 배열 blocks ή files, τα μη έγκυρα URLs και οι άγνωστες τιμές type εντοπίζονται πριν από τη λήψη οποιωνδήποτε αρχείων.