Siirry sisältöön

blocks.json

blocks.json sijaitsee teemasi tai lisäosasi juuressa. Se kertoo CLI:lle, mihin lohkot asennetaan ja mistä rekistereistä etsitään.

Skeema

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

Kentät

$schema

Valinnainen. Osoittaa JSON-skeemaan, jota käytetään editorin automaattiseen täydennykseen ja validointiin.

directory

Pakollinen. Suhteellinen polku kohteesta blocks.json, johon lohkot asennetaan.

Kukin lohko saa oman alikansionsa tässä hakemistossa. Jos directory on blockstudio ja lisäät lohkon hero, tiedostot sijoitetaan kohteeseen blockstudio/hero/.

registries

Pakollinen. Objekti, joka yhdistää nimiavaruuksien nimet rekisteriviittauksiin.

Avain on CLI-komennoissa käytettävä nimiavaruus (npx blockstudio add ui/hero). Arvo on joko URL-merkkijono tai objekti, jossa on url ja valinnaisesti headers.

Merkkijonomuoto (julkiset rekisterit):

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

Objektimuoto (tunnistautumista vaativat rekisterit):

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

Molempia muotoja voi käyttää samassa asetuksessa. Voit määrittää niin monta rekisteriä kuin haluat. Kun lisäät lohkon ilman nimiavaruutta, CLI hakee kaikista niistä.

Tunnistautuminen

Tunnistautumista vaativissa rekistereissä käytetään objektimuotoa, jossa on headers. CLI lähettää nämä otsakkeet jokaisen kyseiseen rekisteriin tekemänsä pyynnön yhteydessä, mukaan lukien sekä registry.json-haun että yksittäisten tiedostojen lataukset.

Bearer-tunniste

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

Perustunnistautuminen

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

Mukautetut otsakkeet

Minkä tahansa otsakkeen voi lisätä. Tämä sopii esimerkiksi API-avaimille, organisaatiotunnisteille tai muille rekisteripalvelimen vaatimille arvoille:

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

Ympäristömuuttujat

Otsakkeiden arvot tukevat syntaksia ${VAR_NAME} ympäristömuuttujien lukemiseen. Näin tunnisteet pysyvät poissa versionhallinnasta.

CLI ratkaisee ympäristömuuttujat suorituksen aikana. Jos viitattua muuttujaa ei ole asetettu, CLI päättyy virheeseen, jossa ilmoitetaan puuttuva muuttuja ja otsake, jossa siihen viitattiin.

Aseta muuttuja komentotulkissa tai CI-ympäristössä. CLI lukee vain prosessin ympäristömuuttujat; se ei lataa .env-tiedostoja itse:

Shell
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

Staattiset otsakearvot (ilman ${...}) välitetään sellaisinaan.

Asetustiedoston etsiminen

CLI etsii nykyisestä työhakemistosta ylöspäin tiedostoa blocks.json. Voit siis suorittaa komentoja projektisi mistä tahansa alihakemistosta.

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

Jos tiedostoa blocks.json ei löydy, CLI kehottaa suorittamaan komennon npx blockstudio init.

Esimerkki: teema ja kaksi rekisteriä

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

Esimerkki: lisäosa ja mukautettu hakemisto

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