Primeiros passos

O HedHog ajuda você a fazer o scaffold de APIs headless, compor bibliotecas reutilizáveis e publicar um painel administrativo modular com permissões RBAC.

Este guia foca na instalação da CLI do HedHog, o ponto de entrada recomendado para criar e gerenciar projetos HedHog.

Antes de instalar a CLI, certifique-se de que seu ambiente tem:

• Node.js 18+
• npm 9+, ou outra versão do npm compatível com a instalação global de pacotes
• pnpm, exigido por vários fluxos de trabalho da CLI
• Git, necessário para clonar templates e gerenciar o controle de versão do projeto
• Docker e Docker Compose, exigidos pelo fluxo de banco de dados padrão em hedhog new

Instale a CLI do HedHog globalmente com o npm:

npm i -g @hed-hog/cli

Após a instalação, confirme que o comando está disponível:

hedhog --version
hedhog --help

Se o hedhog responder no seu terminal, a instalação global está pronta.

Com a CLI instalada, você já pode criar um novo projeto imediatamente:

hedhog new my-project

Depois, entre no diretório do projeto:

cd my-project

Depois que o scaffold estiver pronto, o fluxo habitual de execução local é:

# Instale as dependências se você criou o projeto com --skip-install
pnpm install

# Inicie o ambiente de desenvolvimento local
pnpm dev

Se o seu projeto gerado usa a stack de banco de dados local padrão, certifique-se de que o Docker Desktop ou seu serviço local do Postgres esteja disponível antes de iniciar a aplicação.

Se o template expõe scripts específicos da aplicação, você também pode inspecionar o package.json e usar os comandos direcionados fornecidos ali.

• A primeira execução pode demorar um pouco mais enquanto as dependências, os arquivos gerados ou os containers do banco de dados terminam de inicializar.
• Assim que o servidor de desenvolvimento estiver pronto, abra a URL local exibida no terminal.
• Se o projeto incluir uma aplicação de administração, abra também sua rota local para confirmar que toda a stack está rodando corretamente.

Se você precisar sobrescrever um diretório existente, use:

hedhog new my-project --force

Para atualizar para a versão publicada mais recente, execute:

npm i -g @hed-hog/cli@latest

Para remover a instalação global:

npm uninstall -g @hed-hog/cli

Logo após instalar o Node.js com o winget no Windows, executar npm --version no PowerShell pode falhar com:

npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system.

Isso acontece porque a Política de Execução (Execution Policy) padrão do PowerShell bloqueia a execução de scripts .ps1, inclusive os do npm. Corrija permitindo scripts criados/assinados localmente para o seu usuário:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

• Feche e reabra o terminal após instalar o Node.js com o winget, para que o PATH atualizado seja carregado.
• Execute node --version e npm --version novamente para confirmar que ambos são reconhecidos.

• Feche e reabra seu terminal.
• Confirme que o diretório de binários globais do npm está no seu PATH.
• Execute npm prefix -g para verificar o prefixo global atual do npm.

• No Windows, execute o terminal com o nível de permissão necessário.
• Evite misturar pacotes globais entre diferentes instalações do Node.js.

• Instale o pnpm e valide-o com pnpm --version.
• O comando hedhog new verifica a presença do pnpm antes de iniciar o processo de scaffold.

Quando o hedhog new detecta que o git e/ou o pnpm estão faltando, ele pergunta interativamente: "Would you like to install them automatically now?" Responder "Yes" instala o pnpm automaticamente via npm sem problemas.

Para o git, o gerenciador de pacotes ao qual a CLI recorre depende do que já está presente na máquina. Em sistemas Windows 11 modernos, o winget geralmente já vem pré-instalado (incluído com o App Installer) mesmo quando o Chocolatey não está. Nesse caso, a CLI vai direto para winget install Git.Git em vez de oferecer a instalação do Chocolatey primeiro. Em outras palavras, o gerenciador de pacotes detectado — e, portanto, o caminho exato de instalação seguido — pode variar dependendo do que já estiver disponível na máquina de destino.

Limitação conhecida: se a fonte msstore do winget tiver um problema de certificado, sua busca multi-fonte se torna ambígua e a instalação automática do git falha, mesmo que a fonte winget (não-msstore) funcione bem e já liste o pacote do Git corretamente:

0x8a15005e: The server certificate did not match any of the expected values.

Quando isso acontece, a CLI corretamente recorre à caixa "Required tools missing" e orienta você a instalar o git manualmente. Soluções alternativas: redefinir a fonte do winget (winget source reset --force) ou instalar o git manualmente antes de executar o hedhog new novamente.

Em execuções não interativas (sem TTY — por exemplo, scripts, CI ou vagrant winrm -c "..."), a CLI nunca pergunta: ela vai direto para a caixa "Required tools missing" e encerra com Required tools still missing: git (ou o nome de qualquer ferramenta que esteja ausente).

Quando o hedhog new detecta uma falha de conexão com o Postgres, ele tenta subir um container de banco de dados automaticamente via Docker Compose. No Windows, se a CLI do Docker está instalada (por exemplo, via winget install Docker.DockerDesktop), mas o engine do Docker Desktop nunca foi iniciado, o comando falha mesmo que docker --version funcione normalmente, porque esse comando só se comunica com o cliente do Docker, não com o daemon:

unable to get image 'postgres:18': failed to connect to the docker API at
npipe:////./pipe/docker_engine; check if the path is correct and if the
daemon is running: open //./pipe/docker_engine: The system cannot find the
file specified.

Executar docker info confirma isso: a seção Client: reporta normalmente, enquanto a seção Server: falha com o mesmo erro de named pipe. Você também pode ver Error response from daemon: Docker Desktop is unable to start.

• Atualize o kernel do WSL2: wsl --update.
• Abra o Docker Desktop manualmente e aguarde o ícone da baleia na bandeja mostrar "Running" (verde). Ele pode pedir para você habilitar o WSL2/Hyper-V ou reiniciar o Windows.
• Se você ainda vir "Docker Desktop is unable to start", inicie o engine manualmente pela interface do Docker Desktop (Settings > General).
• Antes de tentar novamente, valide com docker info: ele deve retornar detalhes em Server: sem erro de pipe.
• Execute hedhog new <project> novamente.

Se o hedhog new falhou no meio do processo, a pasta do projeto já foi criada, então tentar novamente com o mesmo nome falha com:

A folder with the name "X" already exists. Process stopped.

Remova a pasta primeiro e tente de novo:

npx rimraf <project>
hedhog new <project>