Configuração

O app.manifest.json descreve o app inteiro num único arquivo JSON. Ele é a fonte da verdade: surfaces, tema, locale, backend e plugins. Esta página é o mapa de cada bloco de topo — o que ele faz e o que o fayz doctor valida.

A forma do manifesto

Um app admin recém-criado se parece com isto (manifestVersion sempre 2 nesta geração):

{
  "manifestVersion": 2,
  "id": "minha-loja",
  "name": "Minha Loja",
  "backend": { "provider": "mock" },
  "locale": { "default": "pt-BR", "supported": ["pt-BR", "en"], "currency": "BRL" },
  "theme": { "brand": "violet" },
  "surfaces": {
    "admin": {
      "scaffold": "admin",
      "plugins": [{ "id": "dashboard" }],
      "pages": []
    }
  }
}

Os quatro campos obrigatórios são manifestVersion, id, name e surfaces. O resto é opcional e tem default sensato.

Os blocos de topo

Campo	Papel
`id`	Identificador em kebab-case (`^[a-z0-9][a-z0-9-]*$`).
`name`	O nome exibido do app.
`backend`	De onde vêm os dados. Objeto `{ provider, ... }` — detalhado abaixo.
`locale`	Idioma, idiomas suportados e moeda.
`theme`	A marca: `brand`, `radius`, `mode` (veja Temas).
`permissions`	Declaração de features e ações (deny-by-default no multi-tenant).
`surfaces`	As faces do app. Pelo menos uma é obrigatória.

O bloco `backend`

O provider decide de onde os dados vêm. Os valores aceitos:

`provider`	Para quê
`mock`	Dados de exemplo em memória, zero configuração. É o default do scaffold. Ao consumir os pacotes em código, os providers mock nascem vazios — veja Mock e dados de exemplo para semeá-los.
`supabase`	Um projeto Supabase real. Acompanha `projectRef`.
`fayz-api`	A API gerenciada do Fayz.
`fayz-shop`	O backend de e-commerce do Fayz.
`custom`	Um adapter próprio, referenciado por `adapterId`.

Trocar de mock para supabase é o passo do meio do tutorial — veja Supabase:

{ "backend": { "provider": "supabase", "projectRef": "seu-project-ref" } }

Surfaces e plugins

Dentro de surfaces, cada surface declara o scaffold (obrigatório), uma lista de plugins e uma de pages. Ligar uma capacidade é adicionar { "id": "..." } à lista plugins — os pacotes já vêm nas dependências do app gerado, então não há nada para instalar nem para editar em src/plugins.generated.ts. Cada pluginRef aceita config (opções do plugin) e enabled (para desligar sem remover).

Como as rotas e o menu são derivados dessa lista, o detalhe está em Rotas e navegação.

Duas formas de configurar

O scaffold entrega a forma manifesto-primeiro: você edita JSON e a plataforma renderiza. Existe também a forma código-primeiro, em que a configuração vive em src/ (via defineSaas / defineStorefront). O fayz doctor reconhece as duas: um app sem app.manifest.json mas com package.json é tratado como app código-primeiro — o doctor roda as checagens de boundary e passa. Comece pela forma manifesto; ela cobre a maioria dos casos e é a que a plataforma edita ao vivo.

Valide sempre

Depois de qualquer edição, rode o doctor. Ele confere a estrutura do manifesto, os plugins referenciados e os limites de arquitetura:

npx @fayz-ai/cli doctor

Um id fora do padrão ou uma surface sem scaffold fazem o doctor sair com erro — de propósito, para você pegar o problema antes de subir. Hoje o doctor valida a estrutura do manifesto e as fronteiras de arquitetura; a validação dos valores de enums (como backend.provider ou theme.brand) está chegando — um fix de SDK está em PR.

Próximo: aplique a sua marca em Temas.