Shopify theme fejlesztés CLI-val, lépésről lépésre

A biztonságos Shopify theme workflow helyi kódból, Git-verziókezelésből, development theme-en futó előnézetből és külön kiadási lépésből áll. Új projektnél theme init, meglévő boltnál theme pull adja a kiindulópontot. Fejlesztés közben theme dev és theme check dolgozik, az elfogadott verzió pedig először unpublished theme-ként kerüljön fel, és csak ezután legyen publikálva.

A Shopify admin kódszerkesztője gyors javításra kényelmes, komolyabb munkánál viszont hamar elfogy körülötte a levegő. Nincs rendes branch, nehézkes a teljes projektben keresni, és egy rossz mentés közvetlenül az élő storefrontot érintheti. A Shopify CLI-val ugyanazt a theme-et a saját editorodban szerkesztheted, Gittel követheted, és valós shopadatokkal nézheted meg anélkül, hogy minden módosítás azonnal a vásárlók elé kerülne.

Ha magát a CLI-t még nem telepítetted, kezdd a Shopify CLI telepítése és frissítése útmutatóval. Az app-, theme- és Hydrogen-parancscsoportok közös térképét a Shopify CLI 3.0 pillar cikkben találod.

Mire lesz szükséged?

A Shopify theme fejlesztéshez kell egy naprakész Shopify CLI, Node.js, Git, egy kódszerkesztő és hozzáférés ahhoz a store-hoz, amelyen tesztelni fogsz. A jelenlegi követelmény Node.js 22.12 vagy újabb, illetve legalább Git 2.28.

A store-hoz többféleképpen kapcsolódhatsz. Használhatsz tulajdonosi fiókot, megfelelő Themes jogosultságú staff accountot, Manage themes jogosultságú collaborator accountot, Theme Access-jelszót vagy megfelelő scope-okkal rendelkező custom app tokent. Az első store-műveletnél a CLI szükség esetén elindítja a böngészős bejelentkezést.

Ellenőrizd az alapokat:

node --version
git --version
shopify version

A példákban a store címe pelda-bolt.myshopify.com. Mindig a tartós myshopify.com domaint használd, ne a storefront egyedi vagy elsődleges domainjét.

Új theme indítása theme init paranccsal

Új theme-projektet a shopify theme init hoz létre. A parancs egy Git repositoryt klónoz a helyi gépedre, amelyből kiindulhatsz:

shopify theme init sajat-theme
cd sajat-theme

Ha nem adsz meg külön repositoryt, a jelenlegi CLI a Shopify Skeleton theme-et használja alapként. Régebbi videókban és cikkekben gyakran Dawn szerepel alapértelmezett starterként, ezért ezt ne vedd automatikusan készpénznek.

Ha kifejezetten egy másik nyilvános Git repositoryból indulnál, add meg a klónozandó URL-t:

shopify theme init sajat-theme \
  --clone-url https://github.com/Shopify/dawn.git \
  --latest

A --latest a megadott repository legfrissebb release-ét tölti le. Saját vagy harmadik féltől származó starter használatakor előbb nézd át a licencet, a karbantartottságot és azt, hogy megfelel-e a Shopify jelenlegi theme-struktúrájának.

Az init új kódbázishoz való. Ha egy működő bolt meglévő theme-jét akarod módosítani, ne inicializálj mellé egy új Skeleton vagy Dawn projektet, mert abból hiányozni fognak a bolt aktuális theme-fájljai és beállításai.

Meglévő Shopify theme letöltése theme pull paranccsal

Meglévő theme-nél hozz létre egy üres projektmappát, lépj bele, majd húzd le a kiválasztott távoli theme-et:

mkdir pelda-bolt-theme
cd pelda-bolt-theme
shopify theme pull --store pelda-bolt.myshopify.com

Ha nem adsz meg theme ID-t vagy nevet, a CLI kilistázza a store theme-jeit, és választást kér. Egyértelmű célpontnál megadhatod közvetlenül is:

shopify theme pull \
  --store pelda-bolt.myshopify.com \
  --theme 123456789

Az első lehúzást érdemes üres mappában elvégezni. Egy már használt helyi könyvtárban a pull a távoli állapothoz igazítja a fájlokat, és alapértelmezésben törölhet olyan helyi theme-fájlt, amely a távoli theme-ben nem létezik. Ha erre nincs szükséged, használd a --nodelete kapcsolót:

shopify theme pull --theme 123456789 --nodelete

Ez sem oldja meg helyetted a konfliktusokat. A pull szinkronizálási művelet, nincs benne Git-szerű háromutas merge. Mielőtt egy meglévő munkamappába pullolsz, legyen tiszta commitod vagy külön mentésed, utána pedig nézd át a változásokat.

A kapcsolt store-t és az aktuális theme-környezetet így ellenőrizheted:

shopify theme info
shopify theme list

Ha másik store-ral dolgoznál, add meg újra a --store értékét. A CLI ezt használja a következő parancsoknál, amíg másikat nem választasz.

Az első Git-állapot rögzítése

A letöltött vagy inicializált theme-et még az első módosítás előtt tedd Gitbe. Így lesz egy visszaállítható alapállapotod:

git init
git add .
git commit -m "Initial Shopify theme baseline"

Ha a theme init által klónozott repository már tartalmaz Git-előzményt, előbb nézd meg a git status és git remote -v kimenetét. Döntsd el, hogy megtartod-e a starter történetét, vagy saját repositoryba viszed tovább a projektet.

Minden új feladathoz nyiss külön branchet:

git switch -c feature/uj-termekoldal

A kisebb, témánként elkülönített commitokat könnyebb review-zni és visszavonni. A config/settings_data.json külön figyelmet kér: ebben tárolódhatnak a Theme Editorban végzett beállítások, így könnyen ütközik a kereskedő vagy egy másik fejlesztő módosításaival.

Ha a repositoryban buildforrások, dokumentációk vagy más, Shopify-ba nem küldendő fájlok is vannak, a theme gyökerében létrehozott .shopifyignore fájllal zárhatod ki őket a CLI pull, push és dev műveleteiből. A kizárás előtt ellenőrizd, hogy az adott fájl valóban nem szükséges a storefront futásához.

Helyi fejlesztés theme dev használatával

A fejlesztői munkamenetet a theme gyökeréből indítsd:

shopify theme dev --store pelda-bolt.myshopify.com --open

A theme dev feltölti a helyi fájlokat egy ideiglenes development theme-be, majd több hasznos linket ad:

• helyi előnézetet, alapértelmezetten a http://127.0.0.1:9292 címen;
• Shopify Theme Editor linket;
• jelszóval védett megosztható preview linket.

A helyi előnézet CSS- és sectionváltozásnál hot reloadot használ, más fájloknál pedig szükség szerint frissíti az egész oldalt. A store valódi termékeivel, kollekcióival és tartalmaival tesztelhetsz, miközben a local fájl marad a fejlesztés elsődleges forrása.

A development theme rejtett és ideiglenes. Nem számít bele a store theme limitjébe, hét nap inaktivitás után törlődik, és a shopify auth logout is eltávolítja. Hosszabb ideig használható ügyfél-preview-hoz töltsd fel unpublished theme-ként, mert a development theme nem tartós staging környezet.

A theme dev normál esetben a helyi theme állapotával cseréli le az adott környezet korábbi development theme-jét. Ha a Theme Editorban végzett módosításokat vissza akarod szinkronizálni a helyi fájlokba, ezt külön engedélyezned kell:

shopify theme dev \
  --store pelda-bolt.myshopify.com \
  --theme-editor-sync

Ezt csapatban csak tisztázott szabályokkal használd. Ha egyszerre szerkesztitek ugyanazt a fájlt a kódszerkesztőben és a Theme Editorban, könnyű elveszíteni vagy összekeverni a módosításokat.

Mit jelent pontosan a development theme?

A development theme nem ugyanaz, mint a helyi szerver és nem ugyanaz, mint egy normál unpublished theme. A CLI ideiglenes távoli theme-et kapcsol a helyi projekthez, a local proxy pedig valós időben mutatja a változásokat.

Környezet	Mire való?	Meddig marad meg?
Helyi preview	Gyors fejlesztés és hot reload	A theme dev munkamenethez kötődik
Development theme	Valós store-adatokkal végzett ideiglenes teszt	Hét nap inaktivitásig, illetve logoutig
Unpublished theme	Tartós preview, QA és ügyfél-jóváhagyás	Amíg nem törlitek vagy publikáljátok
Live theme	A vásárlók által látott storefront	Új theme publikálásáig

A local 127.0.0.1 előnézet checkout customization tesztelésére nem használható. A theme-fejlesztési preview-t kezeld storefront-ellenőrzésként, és az ettől eltérő Shopify-felületeket a saját fejlesztői eszközeikkel teszteld.

Theme Check futtatása

A Theme Check statikusan elemzi a Liquid-, JSON- és theme-kódot, és jelzi a hibákat, illetve a Shopify best practice-ektől való eltéréseket:

shopify theme check

Futtasd rendszeresen fejlesztés közben, és mindenképpen a feltöltés előtt. Saját konfigurációs fájlt így hozhatsz létre:

shopify theme check --init

Az automatikus javítás néhány szabálysértést képes korrigálni:

shopify theme check --auto-correct

Ezt követően mindig nézd át a diffet. Az automatikus javítás technikailag helyes változtatása is érintheti a formázást vagy olyan kódrészt, amelyet a projekt saját konvenciói szerint másképp kezelnél.

A theme check sikeres futása nem helyettesíti a böngészős tesztelést. Nem fogja megmondani, hogy egy section mobilon szétesik, hibás termékadatnál rossz állapotot mutat, vagy lassan tölti be a storefrontot.

Feltöltés unpublished theme-ként

Ha a branch elkészült, a Theme Check rendben lefutott és a preview-t is átnézted, töltsd fel új unpublished theme-ként:

shopify theme push \
  --store pelda-bolt.myshopify.com \
  --unpublished

A parancs új theme-et hoz létre a theme libraryban, feltölti a helyi fájlokat, majd editor- és preview linket ad. Ha szeretnéd megakadályozni, hogy Theme Check hibával kerüljön fel a theme, használd a --strict kapcsolót:

shopify theme push --unpublished --strict

A --strict a hibáknál megállítja a push műveletet, a warningokat viszont engedi. CI-ban a Theme Check saját --fail-level beállításával ennél szigorúbb kaput is készíthetsz.

Egy már létező unpublished theme frissítéséhez add meg annak ID-ját vagy nevét:

shopify theme push --theme 123456789 --strict

Ellenőrizd a targetet minden push előtt. Ha theme ID nélkül indítod a parancsot, a CLI választást kér, de neked kell felismerned, melyik a megfelelő theme.

Preview link készítése és megosztása

Ha gyorsan egy új, véletlenszerű nevű unpublished theme-et és megosztható preview linket szeretnél, erre való a theme share:

shopify theme share --store pelda-bolt.myshopify.com

Meglévő feltöltött theme preview- és editorlinkjét a theme open adja vissza:

shopify theme open --theme 123456789

A theme dev által adott link fejlesztés közben praktikus. Az elfogadásra küldött verzióhoz a theme share vagy egy névvel és ID-val követhető unpublished theme jobb választás. Így a link a kijelentkezés és a development theme automatikus törlése után is használható marad.

QA közben nézd meg legalább a fő template-eket, a mobilos töréspontokat, a navigációt, a kosarat, a keresést, a nyelvi és marketváltozatokat, az üres állapotokat, valamint az app blockokat és app embedeket. Egyetlen jól kinéző kezdőlap kevés bizonyíték arra, hogy a theme kiadható.

Az élő theme védelme

A live theme legyen kiadási célpont. Fejlesztéshez használj development vagy unpublished theme-et, és csak elfogadott verziót publikálj.

A Shopify CLI külön --allow-live kapcsolót kér ahhoz, hogy közvetlenül az élő theme-re pusholj. Ez hasznos védőkorlát, de nem helyettesíti a folyamatot:

# Ezt normál fejlesztési workflow-ban kerüld
shopify theme push --live --allow-live

Régebbi tutorialok gyakran bemutatják a közvetlen live push lehetőségét. A parancs működhet, de egy rosszul kiválasztott target azonnal módosíthatja a vásárlók által látott storefrontot. Ugyanezért a theme push --publish összekapcsolt feltöltés-publikálást is csak automatizált, ellenőrzött kiadási folyamatban érdemes használni.

A biztonságos manuális sorrend:

1. készíts tiszta branchet és kis commitokat;
2. ellenőrizd, történt-e közben távoli módosítás;
3. futtasd a theme dev és theme check lépéseket;
4. pusholj unpublished theme-be;
5. végezd el a QA-t és kérj jóváhagyást;
6. publikáld a konkrét, ellenőrzött theme ID-t;
7. tartsd meg az előző live theme-et gyors rollbackhez.

Publikálás theme publish paranccsal

A theme publish egy már feltöltött unpublished theme-et állít be élő theme-ként. A helyi kódot előbb fel kell töltened, mert a publish önmagában nem végez push műveletet:

shopify theme publish \
  --store pelda-bolt.myshopify.com \
  --theme 123456789

A CLI megerősítést kér. Olvasd el még egyszer a store nevét, a theme ID-t és a theme nevét, mielőtt jóváhagyod. Manuális kiadásnál ne kapcsold ki automatikusan ezt a kérdést.

Publikálás után ellenőrizd az éles storefrontot incognito ablakban és mobilon is. Nézd meg a kritikus vásárlási útvonalat, majd ellenőrizd, hogy az app embedek, analitikai tagek és marketbeállítások a várt módon működnek-e. Ha súlyos hibát találsz, az előző theme visszapublikálása általában gyorsabb és biztonságosabb, mint az élő kód kapkodó javítása.

Mi történik, ha a távoli theme is változik?

Shopify theme-nél két szerkesztési hely könnyen marad egyszerre aktív: a Git repository és a Shopify admin. A merchant módosíthat a Theme Editorban, egy app theme-fájlokat vagy blokkokat adhat hozzá, egy másik fejlesztő pedig közvetlenül a távoli theme-en dolgozhat.

Ha Shopify GitHub integration kapcsolódik a theme-hez, a merchant theme-módosításai commitként megjelenhetnek a kapcsolt branchen. Ez sokat segít a változások követésében. Saját build pipeline esetén viszont külön kell megtervezned, hogy a repository a forráskódot, a Shopify-kompatibilis buildet vagy mindkettőt tárolja.

GitHub integration nélkül jelölj ki egy elsődleges forrást, és egyezzetek meg abban, mikor szerkeszthető a Theme Editor. Kiadás előtt húzd le vagy hasonlítsd össze a releváns távoli változásokat egy tiszta állapottal. A vak pull → push sorrend veszélyes: a pull eltüntethet helyi fájlokat, a push pedig felülírhat friss távoli munkát.

Egy használható napi theme workflow

A parancsok mögötti gondolat fontosabb, mint a parancslista. Egy átlagos fejlesztési nap így nézhet ki:

# Környezet és target ellenőrzése
shopify theme info
git status

# Külön fejlesztési branch
git switch -c feature/announcement-bar

# Helyi fejlesztés
shopify theme dev --store pelda-bolt.myshopify.com

# Kódellenőrzés
shopify theme check

# Változások rögzítése
git add .
git commit -m "Add configurable announcement bar"

# Tartós QA-verzió feltöltése
shopify theme push --unpublished --strict

Az elfogadás után a konkrét theme ID-val publikálhatsz. Több store és development/staging/production környezet esetén a shopify.theme.toml és a --environment kapcsoló leveszi rólad az ismétlődő store-, theme- és ignore-beállítások kézi megadását. Ennek érdemes külön útmutatót szentelni, mert a rosszul beállított environment ugyanúgy rossz targetre viheti a push műveletet.

A Shopify CLI akkor teszi biztonságosabbá a theme fejlesztést, ha a local kód, a Git-előzmény, az ideiglenes preview és az éles kiadás külön szerepet kap. A parancsok gyorsak. A megbízható workflow-t az adja, hogy minden lépésnél tudod, melyik store-t, melyik theme-et és melyik fájlverziót módosítod.