Shopify CLI: setup development

Shopify CLI è lo strumento da riga di comando per sviluppare app, temi e custom extensions. Dal 2023 è scritto in TypeScript e unifica gli ex tool separati. Per ogni sviluppatore Shopify è praticamente obbligatorio. In questa guida vediamo installazione, comandi base e workflow tipici.

Installazione

Requisiti: Node.js 18+, Git, npm. Installa CLI globalmente: npm install -g @shopify/cli@latest @shopify/theme. Verifica installazione: shopify version. Su Windows è raccomandato usare WSL2 per evitare problemi di path Liquid. Su macOS/Linux funziona nativamente.

Login e dev store

Login al tuo account Partner: shopify auth login apre browser per OAuth. Per lavorare su un development store: shopify theme dev --store mystore.myshopify.com. Lo sviluppo locale apre un preview URL temporaneo con hot reload: modifichi file Liquid e vedi il risultato in 1 secondo.

Comandi essenziali tema

shopify theme init: crea nuovo tema da Dawn o altro repo. shopify theme dev: server locale con hot reload. shopify theme pull: scarica tema da store remoto. shopify theme push --unpublished: pubblica un nuovo tema unpublished. shopify theme push --theme=ID: aggiorna tema specifico. shopify theme list: lista temi su store. shopify theme delete: rimuove tema da store.

Comandi essenziali app

shopify app init: crea nuova app (sceglie template Remix, Node, PHP, ecc.). shopify app dev: server locale con tunnel ngrok automatico. shopify app deploy: deploy estensioni (Functions, Checkout UI). shopify app generate extension: aggiunge nuova estensione all'app. shopify app config link: collega app a configurazione remota.

Procedura passo-passo

1. Installa Node.js 18+ e Git.
2. Esegui npm install -g @shopify/cli@latest @shopify/theme.
3. Verifica con shopify version.
4. Crea Partner account su partners.shopify.com.
5. Crea development store dal Partner dashboard.
6. Esegui shopify auth login.
7. Inizia un progetto tema: shopify theme init mytheme.
8. Lavora in locale con shopify theme dev --store dev-store.myshopify.com.
9. Push tema unpublished: shopify theme push --unpublished.
10. Per app: shopify app init mioapp e segui wizard.
11. Sviluppa estensioni: shopify app generate extension e scegli tipo (Checkout UI, Function, ecc.).
12. Deploy app: shopify app deploy.

Workflow tipico

1. Pull del tema live in locale: shopify theme pull --live. 2. Crea branch Git: git checkout -b feature/banner. 3. Avvia dev server: shopify theme dev. 4. Sviluppa modifiche. 5. Test in preview URL. 6. Commit Git. 7. Push come tema unpublished: shopify theme push --unpublished --json. 8. QA sul tema unpublished. 9. Pubblica dal Admin.

Errori comuni e come risolverli

• Hot reload non funziona: alcuni temi vecchi senza Online Store 2.0; aggiorna tema.
• Path Windows con backslash: usa WSL2, evita problemi con Liquid render.
• Push sovrascrive live: senza --unpublished il push sovrascrive il tema attivo; SEMPRE specificalo.
• Auth scaduta: shopify auth logout e rifai login.

Domande frequenti

D: CLI vs upload manuale tema?
R: CLI è molto più veloce, supporta hot reload e Git workflow.

D: Funziona con tema pubblico Shopify?
R: Sì, puoi pull/push qualsiasi tema dello store autorizzato.

D: Dove logga gli errori?
R: Output console dev mode; per app anche su Partner dashboard logs.

Theme Check: linter Liquid

Shopify CLI integra Theme Check, linter che valida Liquid per: errori sintassi, undefined variables, deprecated tags, performance issues, accessibility. Esegui shopify theme check. Genera report con severity (info, warning, error). Configura regole in .theme-check.yml. Best practice: integra Theme Check in pre-commit hook Git o GitHub Actions CI. Previene push di codice rotto in produzione.

App development vs theme development

Differenza chiave: theme è il frontend dello store (Liquid + CSS + JS in browser); app è un servizio esterno che parla con Shopify via API + opzionali estensioni (UI extensions, Functions, theme app blocks). CLI gestisce entrambi: shopify theme per temi, shopify app per app. Workflow tipico agency: 1 repo per tema cliente, 1+ repo per app condivisa multi-cliente. Versioning con Git tags per release tracciabili.

Checklist operativa

Prima di considerare l'argomento implementato correttamente, verifica questa checklist sintetica: configurazione tecnica testata in ambiente di staging o development store, backup attivo prima di ogni modifica critica, documentazione interna aggiornata per il team operativo, training agli operatori che useranno la funzionalità, monitoraggio di metriche chiave (conversion rate, AOV, ticket support) per 30 giorni post-implementazione, revisione legale se l'implementazione tocca aspetti GDPR, fiscali o di pagamento, piano di rollback chiaro nel caso di problemi imprevisti, comunicazione ai clienti se il cambiamento influenza la loro esperienza (es. nuovo checkout, nuovi metodi di pagamento, nuovi tempi di spedizione). Una implementazione tecnica senza queste fasi di accompagnamento spesso non produce i risultati attesi e genera attriti interni o sui clienti.

Risorse utili e community

Per approfondire ulteriormente: la documentazione ufficiale Shopify su shopify.dev e help.shopify.com aggiorna costantemente le guide; il Shopify Community Forum ha thread attivi su quasi ogni argomento con risposte da Shopify Experts; Shopify Partner Academy offre corsi gratuiti per merchant e sviluppatori; YouTube channel ufficiale Shopify pubblica walkthrough delle nuove feature. Per il mercato italiano cerca community come Shopify Italia su Facebook o gruppi LinkedIn dedicati a e-commerce manager italiani: il confronto con altri merchant che vivono problemi simili è una scorciatoia preziosa rispetto a documentazione internazionale generica.

Hai bisogno di aiuto?

Se vuoi un Shopify ottimizzato dal team di G Tech Group, scrivici tramite il modulo di contatto.