Blocks

Um block é um documento JSON que o CMS usa para descrever uma peça de conteúdo — uma página, uma instância de section, uma configuração de app ou um matcher. Blocks são a unidade de versionamento de conteúdo, A/B testing e edição no admin.

Anatomia

Todo block tem um campo __resolveType que diz ao framework qual código invocar. Tudo o mais no JSON são as props para esse código.

 {
  "__resolveType": "site/sections/Hero/HeroBanner.tsx",
  "title": "Bem-vinda à nossa loja",
  "cta": {
    "label": "Comprar agora",
    "href": "/produtos"
  }
} 

Quando o framework vê __resolveType: "site/sections/Hero/HeroBanner.tsx" , ele:

1. Procura a section no registro.
2. Valida o resto do JSON contra a interface Props da section.
3. Renderiza a section com essas props.

Tipos de block

Onde os blocks vivem

Fonte: .deco/blocks/*.json

Um arquivo JSON por block, commitado. O admin sincroniza o diretório nos dois sentidos — edições no admin viram arquivos em .deco/blocks/ e vice-versa.

Bundle: src/server/cms/blocks.gen.json

Um único objeto JSON que mapeia IDs de block para seu JSON. Gerado pelo script generate-blocks :

 npm run generate:blocks 

É o que o framework carrega em runtime. Em lojas em produção, o blocks.gen.json tipicamente fica entre alguns MBs e mais de 10 MB, dependendo do número de páginas e sections no CMS.

Re-export: src/server/cms/blocks.gen.ts

Um módulo fino que o Vite plugin substitui por JSON.parse do .json irmão em load time. Não edite na mão nenhum dos dois.

Como a resolução funciona

Quando chega uma requisição para /produtos/algum-produto :

1. A rota catch-all chama loadCmsPage({ siteName, pathname }) .
2. loadCmsPage chama resolveDecoPage de @decocms/start/cms , que:
   • Procura o block da página por padrão de URL.
   • Percorre cada referência de section na lista da página.
   • Resolve o __resolveType de cada section para um componente registrado.
   • Roda o loader de cada section (se tiver).
   • Devolve uma árvore que o renderer percorre.
3. DecoPageRenderer percorre a árvore e renderiza cada section.

Veja Páginas e rotas para como páginas casam com URLs.

Composabilidade

Blocks referenciam outros blocks. Uma página contém referências de section; uma section pode conter uma referência de loader; um matcher pode conter outros matchers. O CMS resolve o grafo todo de forma preguiçosa.

 {
  "__resolveType": "$live/pages/Page.ts",
  "path": "/produtos/:slug",
  "sections": [
    {
      "__resolveType": "site/sections/Header/Header.tsx"
    },
    {
      "__resolveType": "site/sections/Product/ProductDetail.tsx",
      "loader": {
        "__resolveType": "vtex/loaders/intelligentSearch/productDetailsPage.ts",
        "slug": "{slug}"
      }
    }
  ]
} 

Parâmetros de URL ( {slug} ) são interpolados em tempo de resolução.

Blocks multivariados

Um block pode referenciar um matcher para fazer A/B ou segmentar conteúdo:

 {
  "__resolveType": "$live/matchers/MultivariateBlock.ts",
  "variants": [
    { "matcher": { "__resolveType": "..." }, "block": { "__resolveType": "..." } },
    { "block": { "__resolveType": "..." } }
  ]
} 

O primeiro variant cujo matcher retornar true ganha. Veja Matchers e flags.

ETag e invalidação de cache

O framework calcula um hash de conteúdo (DJB2) sobre os blocks resolvidos e expõe como header ETag. Quando você edita um block no admin e republica, o ETag muda e os caches de CDN/browser invalidam corretamente.

Não é um hash de tamanho de string — é um hash de conteúdo de verdade, então duas versões com mesmo tamanho mas conteúdo diferente invalidam corretamente.

Veja também

• Sections
• Páginas e rotas
• Protocolo do admin
• Vite plugin