Lewati ke konten

blocks.json

blocks.json berada di direktori utama tema atau plugin Anda. File ini memberi tahu CLI tempat menginstal blok dan registry yang harus dicari.

Skema

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

Bidang

$schema

Opsional. Menunjuk ke Skema JSON untuk pelengkapan otomatis dan validasi editor.

directory

Wajib. Jalur relatif dari blocks.json tempat blok diinstal.

Setiap blok mendapat subfolder sendiri di dalam direktori ini. Jika directory adalah blockstudio dan Anda menambahkan hero, file akan ditempatkan di blockstudio/hero/.

registries

Wajib. Objek yang memetakan nama namespace ke referensi registry.

Kuncinya adalah namespace yang digunakan dalam perintah CLI (npx blockstudio add ui/hero). Nilainya berupa string URL atau objek dengan url dan headers opsional.

Format string (registry publik):

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

Format objek (registry terautentikasi):

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

Kedua format dapat dicampur dalam konfigurasi yang sama. Anda dapat mengonfigurasi sebanyak mungkin registry. Saat menambahkan blok tanpa namespace, CLI mencari di semuanya.

Autentikasi

Registry yang memerlukan autentikasi menggunakan format objek dengan headers. CLI mengirim header berikut pada setiap permintaan ke registry tersebut, termasuk pengambilan registry.json maupun unduhan file satu per satu.

Token bearer

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

Autentikasi dasar

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

Header khusus

Header apa pun dapat ditambahkan. Ini berguna untuk kunci API, pengenal organisasi, atau nilai lain yang diminta server registry Anda:

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

Variabel lingkungan

Nilai header mendukung sintaks ${VAR_NAME} untuk membaca variabel lingkungan. Dengan begitu, token tidak perlu disimpan dalam kontrol versi.

CLI menyelesaikan variabel lingkungan saat runtime. Jika variabel yang dirujuk belum diatur, CLI berhenti dengan error yang menyebutkan variabel yang belum diatur dan header tempat variabel itu digunakan.

Atur variabel di shell atau lingkungan CI Anda. CLI hanya membaca lingkungan proses; .env tidak memuat file dengan sendirinya:

Shell
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

Nilai header statis (tanpa ${...}) diteruskan apa adanya.

Penemuan konfigurasi

CLI menelusuri ke atas dari direktori kerja saat ini untuk mencari blocks.json. Artinya, Anda dapat menjalankan perintah dari subdirektori mana pun di proyek.

Kode
my-theme/
  blocks.json        <- found here
  blockstudio/
    hero/
  templates/
    page.php          <- running `npx blockstudio add` here still works

Jika blocks.json tidak ditemukan, CLI meminta Anda menjalankan npx blockstudio init.

Contoh: tema dengan dua registry

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

Contoh: plugin dengan direktori khusus

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