Per iniziare con Zinnector®, la CLI per sviluppatori

Zinnector® è lo strumento da riga di comando gratuito e con licenza MIT di Zinn Digital® per gli sviluppatori WordPress. Crea la struttura di un sito, esegue un vero WordPress sulla propria macchina senza che sia installato altro se non Node — niente Docker, niente MAMP, niente PHP nel proprio PATH — quindi verifica ciò che è stato realizzato confrontandolo con lo spazio di hosting su cui si sta per effettuare il deployment e lo invia. Questa guida consente di passare da zero a un sito in esecuzione in circa due minuti e indica quale sia l'aspetto di un'operazione riuscita in ogni fase, in modo da sapere quando qualcosa è andato storto.

Di cosa hai bisogno

Node 24 o successivo. Eseguire node --version; deve restituire v24 o superiore. Installare la versione LTS corrente da nodejs.org — su Windows winget install OpenJS.NodeJS.LTS, su macOS brew install node@24.
npm, incluso con Node. Zinnector® lo utilizza una sola volta per scaricare il runtime di WordPress nella propria cache.
git, necessario solo per zinnector push — i deployment vengono gestiti dal proprio repository.
Docker, solo se richiesto tramite l'opzione --runtime docker. Il runtime predefinito non ne richiede alcuno.

Nessuna delle operazioni seguenti richiede un account. Una chiave API è necessaria solo quando si raggiunge uno spazio di hosting, come descritto in Deploying with Zinnector®.

Passaggio 1 — installazione

npm install -g zinnector

Se npm stampa npm WARN EBADENGINE, la versione di Node in uso è precedente a quella >=24.18.1 dichiarata dal pacchetto. L'installazione viene comunque completata, ma la CLI rifiuterà di avviarsi. Aggiornare prima Node, quindi ripetere l'installazione.

Passaggio 2 — verifica della versione

zinnector --version

Esito positivo: un numero di versione, ad esempio 0.1.2. Se viene visualizzato "Zinnector® needs Node 24 or newer — this is Node 20.x", il file binario è installato ma la versione di Node è troppo obsoleta; il comando termina con il codice 78 senza eseguire alcuna operazione.

Passaggio 3 — lettura della guida

zinnector --help

Esito positivo: un banner che elenca i cinque comandi del flusso (new, dev, link, check, push) seguito da ciascun comando accompagnato da una breve descrizione di una riga della sua funzione. Ciascun comando accetta inoltre la propria opzione --help — zinnector dev --help elenca i flag relativi a runtime, PHP e porta. L'elenco completo, con relativi esempi, è disponibile nella command reference.

Passaggio 4 — creazione della struttura di un sito

zinnector new my-site

Esito positivo: un'intestazione Created my-site e l'elenco dei file scritti — zinnector.json, un albero wp-content contenente plugins/, themes/ e un file di supporto mu-plugins/, un file .gitignore e un README — seguiti dai comandi successivi da eseguire. Nessun elemento al loro interno è un segnaposto; il progetto si avvia così com'è. Le opzioni --template plugin o --template theme creano la struttura di un plugin o di un block theme che si attiva non appena viene creato.

Passaggio 5 — esecuzione

cd my-site
zinnector dev

La prima volta, Zinnector® richiede una conferma prima di scaricare il runtime di WordPress — circa 570 MB, poiché include ogni build di PHP dalla 5.2 alla 8.5 — all'interno della propria directory di cache, senza mai inserirli nel progetto. Rispondere Y, oppure passare --yes per saltare la domanda. Su Node 26 o versioni successive, recupera anche una versione di Node 24 esclusivamente per il runtime (circa 30 MB, verificati tramite i checksum di nodejs.org), poiché il modulo nativo del runtime dispone di file binari precompilati solo per Node 24 e 25; non sono necessari un compilatore o Visual Studio.

Esito positivo: un blocco che indica il nome del progetto, la versione di PHP e la versione di WordPress, seguito da:

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

Passaggio 6 — apertura

Visitare http://127.0.0.1:9400 in un browser. Esito positivo: un nuovo sito WordPress intitolato My WordPress Website, servito dalla versione di PHP richiesta. http://127.0.0.1:9400/wp-admin apre la bacheca con l'accesso già effettuato. Inserendo un plugin in wp-content/plugins/ o un tema in wp-content/themes/, questo sarà immediatamente disponibile al successivo ricaricamento della pagina: il runtime serve tali directory direttamente dal progetto.

Premere Ctrl-C per interrompere. zinnector dev --once avvia il runtime, stampa le informazioni su ciò che è effettivamente in esecuzione (versione PHP, versione WordPress, estensioni caricate) e si arresta; utile quando si desidera una conferma concreta anziché una previsione.

Passaggi successivi

Local development with zinnector dev — i due runtime, la scelta delle versioni di PHP e WordPress e quali elementi vengono serviti e da dove.
Deploying with Zinnector® — accesso, associazione del progetto a uno spazio, verifica preliminare, invio.
The command reference — tutti i comandi, i flag e gli esempi.
Troubleshooting — gli errori più comuni riscontrati dagli utenti e la relativa soluzione.

La stessa documentazione è disponibile nel file README del pacchetto su npm e su GitHub, dove segnalazioni di problemi e pull request sono ben accette.