Primeiros passos com o Zinnector®, a CLI do desenvolvedor

O Zinnector® é a ferramenta de linha de comando gratuita e sob licença MIT da Zinn Digital® para desenvolvedores WordPress. Ele estrutura um site, executa um WordPress real em sua própria máquina sem nada instalado além do Node — sem Docker, sem MAMP, sem PHP em seu PATH — depois compara o que você construiu com o slot de hospedagem no qual você está prestes a fazer o deploy e o envia. Este guia leva você do zero a um site em execução em cerca de dois minutos, e informa o que esperar de sucesso em cada etapa para que você saiba quando algo tiver dado errado.

Do que você precisa

• Node 24 ou mais recente. Execute node --version; deve exibir v24 ou superior. Instale a versão LTS atual a partir de nodejs.org — no Windows winget install OpenJS.NodeJS.LTS, no macOS brew install node@24.
• npm, que vem com o Node. O Zinnector® o utiliza uma única vez, para baixar o runtime do WordPress em seu próprio cache.
• git, apenas para zinnector push — os deploys são realizados a partir do seu repositório.
• Docker, apenas se você solicitar com --runtime docker. O runtime padrão não precisa de nenhum.

Nada abaixo exige uma conta. Uma chave de API só é necessária quando você alcançar um slot de hospedagem, em Fazendo deploy com o Zinnector®.

Etapa 1 — instale-o

npm install -g zinnector

Se o npm exibir npm WARN EBADENGINE, seu Node é mais antigo do que a versão >=24.18.1 que o pacote declara. A instalação termina de qualquer maneira, mas a CLI se recusará a executar. Atualize o Node primeiro e, em seguida, instale novamente.

Etapa 2 — verifique a versão

zinnector --version

Sucesso: um número de versão, por exemplo 0.1.2. Se você vir "Zinnector® needs Node 24 or newer — this is Node 20.x", o binário está instalado, mas seu Node é muito antigo; o comando é encerrado com o código 78 em vez de fazer qualquer coisa.

Etapa 3 — leia a ajuda

zinnector --help

Sucesso: um banner listando os cinco comandos do fluxo (new, dev, link, check, push) e, em seguida, cada comando com sua finalidade em uma linha. Cada comando também aceita seu próprio --help — zinnector dev --help lista as flags de runtime, PHP e porta. A lista completa, com exemplos, está na referência de comandos.

Etapa 4 — estruture um site

zinnector new my-site

Sucesso: um cabeçalho Created my-site e uma lista dos arquivos que ele gravou — zinnector.json, uma árvore wp-content com plugins/, themes/ e um utilitário mu-plugins/, um .gitignore e um README — seguidos pelos próximos comandos a serem executados. Nada nele é um placeholder; o projeto inicializa exatamente como está. --template plugin ou --template theme estruturam um plugin ou um tema de blocos que é ativado no instante em que passa a existir.

Etapa 5 — execute-o

cd my-site
zinnector dev

Na primeira vez, o Zinnector® pergunta uma vez antes de baixar o runtime do WordPress — cerca de 570 MB, porque ele contém todas as compilações do PHP do 5.2 ao 8.5 — em seu próprio diretório de cache, nunca dentro do seu projeto. Responda Y, ou passe --yes para ignorar a pergunta. No Node 26 ou mais recente, ele também baixa um Node 24 exclusivamente para o runtime (cerca de 30 MB, verificado em relação aos checksums do nodejs.org), porque o módulo nativo do runtime possui binários pré-compilados apenas para o Node 24 e 25; você não precisa de um compilador nem do Visual Studio.

Sucesso: um bloco que informa o projeto, a versão do PHP e a versão do WordPress e, em seguida:

✔ running at http://127.0.0.1:9400
  admin: http://127.0.0.1:9400/wp-admin  (already signed in)

Etapa 6 — abra-o

Acesse http://127.0.0.1:9400 em um navegador. Sucesso: um novo site WordPress com o título My WordPress Website, servido pela versão do PHP que você solicitou. http://127.0.0.1:9400/wp-admin abre o painel já autenticado. Adicione um plugin em wp-content/plugins/ ou um tema em wp-content/themes/ e ele estará lá no próximo recarregamento — o runtime serve esses diretórios diretamente do seu projeto.

Pressione Ctrl-C para parar. zinnector dev --once inicializa o runtime, exibe o que está realmente em execução (versão do PHP, versão do WordPress, extensões carregadas) e para — útil quando você deseja uma confirmação real em vez de uma promessa.

Para onde ir em seguida

• Desenvolvimento local com zinnector dev — os dois runtimes, a escolha das versões do PHP e do WordPress e o que é servido de onde.
• Fazendo deploy com o Zinnector® — faça login, vincule o projeto a um slot, realize a verificação prévia, faça o envio.
• A referência de comandos — todos os comandos, flags e exemplos.
• Solução de problemas — os erros que os usuários realmente encontram e a solução para cada um.

A mesma documentação está no README do pacote no npm e no GitHub, onde issues e pull requests são bem-vindos.