Os dois caminhos
Tem dois jeitos de construir com a Fayz SDK, e escolher o certo no começo economiza retrabalho. Ou você usa o App Fayz — um shell de admin completo montado a partir da sua config — ou vai de Fayz Headless, consumindo o core e os bundles de plugin direto no seu próprio projeto. Os dois usam os mesmos plugins e o mesmo backend; muda quem é dono da casca em volta dos plugins.
Regra de bolso: se o produto é o app de gestão (um SaaS multi-tenant, um admin), vá de App Fayz. Se você já tem um site próprio — uma landing page, uma loja com marca forte — e só quer plugar algumas capacidades dentro dele, vá de Headless.
App Fayz
Você declara a config do app — em app.manifest.json ou em código com defineSaas — liga um conjunto de plugins, e ganha um app pronto: shell de admin, navegação gerada a partir dos plugins, troca de tenant, permissões e telas de CRUD. É o caminho mais rápido para um produto multi-tenant completo, e é o que o fayz create admin gera para você.
import { defineSaas } from '@fayz-ai/saas'
import { createAgendaPlugin } from '@fayz-ai/plugin-agenda'
import { createCrmPlugin } from '@fayz-ai/plugin-crm'
export default defineSaas({
name: 'Minha Clínica',
plugins: [createAgendaPlugin(), createCrmPlugin()],
})
// → shell de admin completo: navegação, tenants, permissões, CRUD
Você entra pelo Quickstart, que gera exatamente esse tipo de app e o sobe em modo mock. Consumindo os pacotes em código, os providers mock nascem vazios — Mock e dados de exemplo mostra como semeá-los.
Fayz Headless Beta
Você importa @fayz-ai/core e monta as superfícies você mesmo, injetando os bundles de plugin ({ manifest, Provider }) e servindo os subpaths deles em /public. É o caminho para um site sob medida — marketing, loja, portal — que só quer algumas capacidades do Fayz sem adotar o shell inteiro. O tema herda dos seus próprios tokens, então o plugin se parece com o seu site, não com o admin padrão.
O caminho Headless é real e está em uso, mas tem menos documentação que o App Fayz hoje. Espere se apoiar mais na leitura dos tipos e dos exemplos, e menos em guias passo a passo, enquanto ele amadurece.
Comparação
| App Fayz | Fayz Headless | |
|---|---|---|
| Quem monta o shell | a SDK (pronto) | você, no seu projeto |
| Navegação / rotas | geradas do manifesto | você conecta as suas |
| Multi-tenant + permissões | incluídos | você integra o que precisar |
| Tema | shell e tokens do Fayz | herda dos seus próprios tokens |
| Ponto de partida | fayz create admin | um site seu já existente |
| Melhor para | SaaS / admin de gestão | site com marca própria + algumas capacidades |
| Custo de entrada | mínimo — roda em minutos | maior — você é dono da integração |
| Documentação hoje | completa | em amadurecimento |
O que você ganha no App Fayz — shell, navegação, tenancy — é exatamente o que você abre mão de controlar. O Headless inverte: você controla tudo, e paga isso montando a integração. Nenhum é "melhor"; depende de o produto ser o app de gestão ou um site que consome capacidades.