Shopify CLI e integrazione Github: una guida per l'uso

Quest'anno sono state annunciate tantissime novità durante la conferenza Shopify Unite. Si tratta di cambiamenti strutturali al funzionamento dei temi, e come sviluppatori e agenzie abbiamo tanto da testare, con cui familiarizzare e da poi portare in produzione.

Per questo ho pensato di mettere insieme una sorta di "piano di studi" che ha lo scopo di gradualmente farmi familiarizzare con la documentazione e allo stesso tempo testare le nuove funzionalità traducendole in codice. Se vorrete, potrete seguire il mio percorso in una serie di articoli che pubblicherò periodicamente. La prima parte di ciascun articolo conterrà una serie di risorse per esplorare la documentazione, mentre la seconda una serie di istruzioni da seguire per mettere in pratica quanto letto.

Il primo passo è sicuramente configurare un development store e acquisire familiarità con Shopify CLI (Command Line Interface), lo strumento che Shopify consiglia per lo sviluppo di temi per il negozio online 2.0. Fino ad ora, ero abituata a sviluppare temi utilizzando ThemeKit. Questo è ancora lo strumento consigliato da Shopify per lavorare sui temi legacy, tuttavia si consiglia di non utilizzarlo più come app privata, ma di installare l'app Theme Kit Access. Esistono due versioni di Shopify CLI, una per i temi e una per le app: in quest'articolo parlerò di quella specifica per i temi.

Documentazione

• Shopify CLI
• Elenco di comandi per Shopify CLI 
• Come installare Shopify CLI
• Integrazione GitHub per Shopify
• Dawn, il nuovo tema di Shopify
• Come usare la Command Line

Istruzioni step-by-step

Creazione di un nuovo development store

Una premessa per chi è non ha mai sviluppato su Shopify. Per imparare a costruire temi e app, Shopify consente ai suoi partner di creare development store, ossia degli account gratuiti con delle limitazioni. Potete registrarvi come partner Shopify su questa pagina.

1. Nella dashboard partner, sezione negozi, clicca su Aggiungi negozio. Il tipo di negozio dovrà essere un development store, con l'anteprima sviluppatore e la global nav. Come specificato nella documentazione Shopify, i negozi con anteprima sviluppatore non possono essere trasferiti ai clienti.
2. Prendi nota dello url del nuovo negozio perché ti servirà in alcuni dei comandi di Shopify CLI
3. Una volta entrato nel development store, nelle impostazioni → utenti e autorizzazioni aggiungi un nuovo staff account che abbia una mail diversa da quella dell'account partner con cui hai creato il negozio. Ti verrà mandata una mail per effettuare il login e ora potrai utilizzare tutti i comandi della Shopify CLI

Shopify CLI

1. Segui le istruzioni per scaricare Shopify CLI
2. Con il comando

   shopify login --store=yourstorenamemyshopify.com

   potrai effettuare il login al tuo negozio. Ricordati di sostituire yourstorenamemyshopify.com con l'url del tuo negozio. Questo comando farà aprire una finestra del browser dalla quale dovrai fare login.
3. Per verificare se si è connessi al proprio negozio direttamente dalla command line, può essere usato il comando shopify store, che stampa nella console l'url del negozio a cui si è connessi.
4. Con Shopify CLI potrai aggiungere dei prodotti test al negozio. Con il comando shopify populate products ad esempio vengono creati 5 prodotti random. Passando, invece che products, customers o orders si possono generare anche clienti o draft order. Consiglio di creare una decina di prodotti con questo comando.

   I prodotti creati tramite shopify populate non saranno ancora disponibili sul negozio online. Bisogna aggiungerlo come canale di vendita dall'admin. Vai sull'admin del negozio e seleziona "negozio online" come canale di vendita. Dato che sei già nella dashboard prodotti, aggiungi questi attributi a 3 dei prodotti appena creati, in modo da averli già disponibili per testare le nuove funzionalità dell'Online Store 2.0

   • immagini prodotto
   • opzione colore con alcune varianti per due dei prodotti
   • prezzo di confronto per uno dei prodotti, in modo da poter visualizzare nel tema il prezzo scontato ed eventuali tag che indicano che il prodotto è in saldo.

Cominciamo a lavorare con Dawn

Dawn è il tema open source presentato durante Unite come il nuovo standard per lo sviluppo di temi Shopify. Naviga tramite la command line nella cartella in cui vuoi salvare il tema e con shopify theme init clona il tema da GitHub. Direttamente dalla command line, potrai scegliere il nome da dare al tema.

Diamo una veloce occhiata alla nuova struttura del tema Dawn. Le principali cartelle sono rimaste le stesse, quindi abbiamo la cartella layout, templates, sections, assets eccetera. Dawn ha una struttura modulare, e questo si nota già dal numero di file .css e .js all'interno della cartella assets, ciascuno dei quali contiene del codice per il proprio componente. Nella cartella templates invece si può notare anche che quasi tutti i file, tranne gift_card.liquid, sono in formato .json, compatibile con l'Online Store 2.0.

A questo punto, se vuoi vedere il nuovo tema in azione, sempre dalla command line puoi spostarti con cd all'interno della cartella creata per il nuovo tema e usare il comando shopify theme serve per avviare il server locale. Questo comando genererà 3 link:

• link al server locale
• link per accedere al theme editor
• link alla preview cliente

In breve, shopify theme serve crea una versione "fantasma" del tema ma non pubblicata nel negozio, quindi non sarai in grado di accedervi dal pannello di controllo Shopify ma solo dall'URL del server locale da un altro dei due link generati dalla CLI. Una cosa a cui fare attenzione, in termini di flusso di lavoro: se hai modificato i contenuti al tuo tema di sviluppo tramite l'editor del tema (secondo link generato), puoi trasferire le modifiche al template utilizzando il comando shopify theme pull. Ti sarà presentata una lista di temi disponibili, tra i quali quello di sviluppo locale.

Una volta finito di lavorare con shopify theme serve, puoi pubblicare il tema di sviluppo sul negozio usando shopify theme push —unpublished.

Integrare Shopify e GitHub

Poiché sono abituata a usare GitHub per il mio flusso di lavoro sui temi, ho voluto provare la nuova integrazione di GitHub, che è stata anche annunciata durante Unite.

Innanzitutto, bisogna creare un nuovo repository (privato) su GitHub e collegarlo con il tema che abbiamo nel nostro ambiente locale. Seguendo le istruzioni di GitHub:

1. Dopo aver navigato nella cartella in cui è salvato Dawn, usa git init. Con questo comando verrà inizializzato il repository localmente
2. Aggiungi i file con git add .
3. Con git commit -m "initial upload" crea il primo commit
4. Per configurare la default branch, usa git branch -M main
5. Collega il tuo repository locale con quello creato su GitHub git remote add origin
6. git push -u origin main

Ora siamo pronti a integrare Shopify con GitHub

1. Nel tuo repository, crea una branch da main con il nome della feature sulla quale vuoi lavorare. Ad esempio, la mia si chiama feature/about-page-template perché voglio creare un nuovo template pagina
2. Nella dashboard, seleziona "collega da GitHub" 
3. Quest'opzione aprirà un pannello sulla destra, dove si potrà fare login su GitHub e poi scegliere il repository e la branch da collegare al negozio
4. Seleziona la branch. Una volta cliccato su "collega", verrà creato un tema con il nome della branch selezionata. Sotto il nome del tema, apparirà un'icona GitHub per indicare che il tema è connesso 
5. Se vorrai poi disconnettere il tema dalla branch, lo potrai fare direttamente dalle azioni del tema Shopify.

Con l'integrazione GitHub, i commit che aggiungerò alla branch remota verranno automaticamente deployed al tema Shopify. Gli aggiornamenti funzioneranno anche nell'altra direzione, per cui ogni volta che qualcosa sarà cambiato nel theme editor, come ad esempio l'immagine di un blocco in una sezione oppure la dimensione del font, Shopify creerà un commit con la nuova versione del template direttamente su GitHub.

EXTRA: Aggiungere azioni GitHub al repository

Shopify consiglia di utilizzare le azioni GitHub per mantenere alta la qualità del tema. Imposterò entrambe le azioni indicate nel readme di Dawn sul mio repository, la Lighthouse CLI e theme check di Shopify CLI. L'azione relativa a Google Lighthouse funziona tramite un'app privata, in modo simile a come funzionava il Theme Kit, quindi dovrai abilitare le app private nel tuo development store e creare una nuova app con permessi per accesso in scrittura/lettura al tema.

1. Aggiungi alcuni secrets al tuo repository GitHub in modo che l'azione possa interagire con il tuo negozio Shopify in maniera sicura. I secrets saranno quelli dell'app privata che hai creato in precedenza (chiave API, segreto API), l'url del tuo negozio (solo dominio.myshopify.com) e la password del negozio online, poiché stai eseguendo l'audit su negozio protetto da password.
   Ci sono anche dei parametri opzionali che si possono aggiungere all'azione GitHub, come ad esempio l'handle del prodotto o della collezione sulle quali effettuare l'analisi performance di Lighthouse. Se non vengono inseriti questi parametri, l'audit sarà effettuato sul primo prodotto e la prima collezione del negozio. Questi sono i segreti che ho inserito nel mio repository.
2. Su GitHub, clicca su "Actions" e poi seleziona "Add new workflow"
3. Aggiungi al workflow il codice che trovi a questo repository
4. Salva il workflow aggiungendo il commit al repository. Poiché l'azione che abbiamo aggiunto viene eseguita ogni volta che del codice è aggiunto a main, entrambe le azioni saranno eseguite.

Come funziona l'azione Lighthouse? Creerà un tema di sviluppo ed eseguirà 3 audit su 3 ciascuna di queste 3 pagine: la home page, la pagina prodotto e la pagina collezione. Una volta eseguita, stamperà come risultato dell'azione gli URL per la mediana tra i 3 rapporti eseguiti. Il report sarà basato su un'analisi delle pagine solo su mobile, e non su entrambe mobile e desktop.

Qui il codice delle due azioni che abbiamo appena aggiunto al nostro repository:

Theme Check Action

Lighthouse CI Action

Riflessioni finali

In quest'articolo, abbiamo effettuato il setup del nostro development store, inclusa la creazione di alcuni prodotti di prova. Abbiamo scaricato poi tramite Shopify CLI il nuovo tema di Shopify Dawn da GitHub e l'abbiamo caricato in un repository privato dove abbiamo impostato il deployment continuo e alcune azioni di GitHub che controllano la qualità del nostro tema.

Sono rimasta piacevolmente colpita dal nuovo toolkit e sto iniziando a pensare a come si potrebbero implementare questi flussi di lavoro in produzione.

Probabilmente manterrei le mie due branch principali di GitHub, main e staging, collegate rispettivamente al tema live e a un secondo tema chiamato [Staging].

Quindi, per lavorare su una nuova funzionalità da aggiungere al tema, creerei una branch ad-hoc sulla quale salvare il mio lavoro, ma non la connetterei subito a un nuovo tema Shopify. Invece, durante lo sviluppo utilizzerei Shopify CLI per e il comando shopify theme serve per lavorare sul mio ambiente locale e poi shopify theme push --unpublished, che carica il tema nel mio negozio come nuovo tema non pubblicato. Pubblicare il tema da Shopify CLI dà un buon punto di partenza una volta ripreso a lavorare sulla specifica feature, poiché si continuerebbe a utilizzare nel tema di sviluppo theme serve e shopify theme push --themeid per pubblicare le modifiche più recenti.

Una volta completato il mio lavoro sulla feature, utilizzerei GitHub per fare merge della mia branch con la staging branch, che è già connessa al tema [Staging] del negozio e che probabilmente ha già altre feature che devono essere approvate dal cliente. Il cliente o un project manager poi farà una revisione della feature, che una volta approvata può essere merged con la main branch, connessa al tema pubblicato.

-

Hai già provato a usare Shopify CLI e la nuova integrazione GitHub? Che te ne pare? Sarei curiosa di sapere cosa ne pensi e che workflow hai implementato nel tuo negozio. Puoi scrivermi a rossella@namastudio.it