Desenvolvimento de módulos

Módulos são a forma de estender um projeto HedHog. Em vez de escrever SQL, controllers, DTOs e tabelas de permissão à mão, você descreve uma tabela em YAML e deixa a CLI gerar a migration, uma API CRUD completa e as permissões de rota/papel que a protegem. Este guia percorre esse fluxo de ponta a ponta construindo um pequeno módulo catalog com uma tabela product.

Ao final, você terá:

uma nova biblioteca criada em libraries/,
uma tabela product definida em YAML e aplicada por meio de uma migration,
uma API CRUD funcional com permissões em nível de rota,
e uma página de administração para gerenciar os registros.

Fluxo de desenvolvimento

Criar a biblioteca.
Definir a tabela em YAML.
Gerar e aplicar a migration.
Popular dados iniciais (opcional).
Sincronizar as permissões de rota e papel.
Construir a experiência de admin/frontend.

1. Criar a biblioteca

Crie o scaffold de uma nova biblioteca com a CLI e, então, instale para que o workspace a reconheça:

hedhog dev create-library --name catalog
pnpm install

Isso cria libraries/catalog/ com o diretório hedhog/ padrão (table/, data/, query/, frontend/) e integra o pacote ao monorepo.

2. Definir a tabela em YAML

Uma tabela fica em libraries/<library>/hedhog/table/<table>.yaml. O nome do arquivo, em snake_case, se torna o nome da tabela no PostgreSQL — então product.yaml cria uma tabela product.

# libraries/catalog/hedhog/table/product.yaml
columns:
  - type: pk
  - name: name
  - name: price
    type: decimal
    precision: 12
    scale: 2
  - type: created_at
  - type: updated_at

O que cada linha faz:

Linha	Significado
`type: pk`	Chave primária `id` serial. Sempre prefira isto a `isPrimaryKey`.
`name: name`	Uma coluna "simples" sem `type` é um `VARCHAR` implícito — uma convenção comum do repositório.
`type: decimal` + `precision`/`scale`	Uma coluna monetária `DECIMAL(12, 2)`.
`type: created_at` / `updated_at`	Colunas de auditoria `TIMESTAMPTZ`. `updated_at` também ganha um trigger que a atualiza a cada `UPDATE`.

Para cada tipo de coluna, alias, chave estrangeira e a tabela locale gerada automaticamente, consulte a referência completa do Hedhog YAML.

3. Gerar e aplicar a migration

Quando uma biblioteca é adicionada, a CLI executa este pipeline:

Varre libraries/<library>/hedhog/table/ em busca de definições de schema — um arquivo por tabela.
Pareia cada tabela com seus dados de seed em hedhog/data/ (correspondidos pelo nome do arquivo).
Gera uma migration PostgreSQL (CREATE TABLE, índices, constraints de FK, INSERTs) em apps/api/prisma/migrations/.
Aplica a migration através do Prisma.

hedhog add catalog

Política do monorepo: em um repositório migration-first, nunca edite apps/api/prisma/schema.prisma à mão e nunca resete ou recrie migrations existentes. Quando um YAML de table/ ou data/ mudar, adicione uma nova migration SQL em apps/api/prisma/migrations/ que espelhe a mudança e, então, aplique-a com pnpm prisma:deploy a partir de apps/api.

4. Popular dados iniciais (opcional)

As linhas de seed vão em libraries/<library>/hedhog/data/<table>.yaml, correspondidas à tabela pelo nome do arquivo. Cada entrada da lista é uma linha:

# libraries/catalog/hedhog/data/product.yaml
- name: Starter plan
  price: 19.90
- name: Pro plan
  price: 49.90

As colunas id, created_at e updated_at são preenchidas automaticamente, então você lista apenas as colunas de negócio.

5. Sincronizar as permissões de rota e papel

Os endpoints do CRUD são protegidos por permissões de rota. Dois arquivos os mantêm sincronizados — ambos em libraries/<library>/hedhog/data/.

Declare o papel de admin da biblioteca em role.yaml:

# libraries/catalog/hedhog/data/role.yaml
- slug: admin-catalog
  name:
    en: Catalog Administrator
    pt: Administrador de Catálogo
  description:
    en: Administrator with full access to catalog management.
    pt: Administrador com acesso total à gestão de catálogo.

Em seguida, mapeie cada endpoint para os papéis que podem chamá-lo em route.yaml. Sempre inclua o papel global admin mais o papel específico da biblioteca admin-catalog:

# libraries/catalog/hedhog/data/route.yaml
- url: /product
  method: GET
  relations:
    role:
      - where:
          slug: admin
      - where:
          slug: admin-catalog
- url: /product
  method: POST
  relations:
    role:
      - where:
          slug: admin
      - where:
          slug: admin-catalog

Mantenha route.yaml e role.yaml em sincronia com a API sempre que a URL, o método, a autenticação ou os papéis de um endpoint mudarem — inclusive quando um endpoint for removido. Veja a referência de comandos da CLI para conhecer a ferramenta que ajuda a automatizar isso.

6. Construir a experiência de admin

Com a API e as permissões no lugar, adicione a página de administração que lista e edita os registros. Uma página de listagem padrão usa um PageHeader, uma linha de KPIs, uma barra de busca/filtro plana com uma tabela ou visualização em cards, e um rodapé de paginação — com um formulário baseado em sheet para criar/editar. Reutilize os primitivos compartilhados (EntityPicker, useFormDraft, ResizableSheetContent, os componentes de KPI e busca) em vez de construir variantes locais.

Depois de adicionar ou alterar páginas de admin e seus arquivos de mensagens, sincronize-os de volta para a biblioteca:

hedhog dev assets-to-library catalog

Checklist recomendado

Mantenha os limites de arquitetura claros: lógica de negócio em libraries/*, entrypoints em apps/*, utilitários compartilhados em packages/*.
Reutilize componentes compartilhados antes de criar variantes locais.
Mantenha route.yaml/role.yaml sincronizados com os endpoints ativos.
Valide lint/build/testes focados nas áreas que você tocou.

Próximos passos

Referência do Hedhog YAML — cada tipo de coluna, relacionamento e padrão de seed.
Referência de comandos da CLI — new, add, update e os subcomandos dev.
Módulos — explore o módulo Core e os módulos Enterprise que acompanham o HedHog.