Shopify GitHub-integratie in de praktijk

Een Shopify-thema pas je meestal aan in de editor van Shopify. Dat gaat snel, maar je ziet achteraf niet wat er veranderd is, door wie en waarom. Bij XXLplant, de webshop van ZAZU zelf, werken we daarom met een thema dat aan GitHub gekoppeld is. Tussen 8 juni en 27 september 2026 legde die koppeling 279 wijzigingen vast.

Dit artikel is voor developers die een Shopify-winkel met meer mensen onderhouden, of die AI-agents aan een thema laten werken. Het gaat over hoe de koppeling werkt, wat er wel en niet in de repository terechtkomt, hoe we met de commandoregel werken, en welke valkuilen we tegenkwamen.

Hoe de Shopify GitHub-integratie werkt

Shopify koppelt een thema aan één branch in een GitHub-repository. Vanaf dat moment houden die twee elkaar in beide richtingen bij. Een push naar de branch verschijnt in het thema. Een wijziging in de editor van Shopify komt als commit terug in de branch, met shopify[bot] als auteur.

Bij XXLplant is de verhouding tussen die twee veelzeggend. Van de 279 commits kwamen er 277 van shopify[bot] en 2 van een persoon. Dat komt doordat wij vooral met de commandoregel in het thema werken, en Shopify elke wijziging die zo binnenkomt ook als commit vastlegt. De repository is dus de volledige geschiedenis van het thema, ongeacht waar de wijziging vandaan kwam.

Wat er wel en niet in je GitHub-repository staat

Dit staat er wel in: de Liquid-sjablonen en secties, de snippets, de assets, de JSON-sjablonen met de instellingen per pagina, config/settings_data.json met de thema-instellingen, en de taalbestanden in locales/. Alles wat je in de editor aan een sectie instelt, belandt in een JSON-bestand en dus ook in git.

Dit staat er niet in, en dat verrast bijna iedereen:

• Vertalingen van de inhoud van het thema. Vertaal je een kop uit een sectie via de vertaal-app of via translationsRegister, dan bewaart Shopify die vertaling buiten de themabestanden. Alleen de taalbestanden in locales/ staan in git.
• Metafields en metaobjecten. De teksten van een soortpagina of de vragen in een FAQ-blok leven in de database van de winkel.
• Menu's, producten, collecties en de instellingen van markten.

Voor een winkel in negen talen betekent dat: de repository bewaart de vorm, de winkel bewaart de inhoud. Wie een thema terugzet naar een oude commit, zet de vertalingen dus niet mee terug. Bij XXLplant registreerden we op 5 oktober ongeveer tweeduizend vertalingen van thema-inhoud. Die staan in Shopify. Wil je ze kunnen terugzetten, bewaar dan ook de scripts en exports waarmee je ze schreef, want git doet dat niet voor je.

Hoe je met de Shopify CLI en de API in je thema werkt

Voor losse bestanden gebruiken we de Shopify CLI: shopify theme pull en shopify theme push met --only om één bestand te verplaatsen. Op het live-thema vraagt de CLI om --allow-live, zodat je niet per ongeluk de verkeerde omgeving overschrijft.

Voor geautomatiseerd werk, zoals een agent die twintig sjablonen tegelijk aanpast, gebruiken we de Admin GraphQL-API via shopify store execute. De mutatie themeFilesUpsert schrijft een of meer bestanden in één keer weg, en de query theme(id) { files } leest ze terug. Het voordeel is dat je de bestandsinhoud als variabele meegeeft en de uitvoer als JSON terugkrijgt, zodat een script kan controleren wat er echt is opgeslagen.

Dat controleren is nodig. Shopify valideert een JSON-sjabloon tegen het schema van de secties, en gooit een instelling weg die het schema niet kent. Je push lijkt dan gelukt, maar de instelling is weg. Lees na elke push het bestand terug en vergelijk het.

Welke valkuilen je tegenkomt met een Shopify-thema in GitHub

Dit zijn de dingen die ons tijd kostten, met wat we er nu aan doen.

Een glob in --only kan bestanden verwijderen

shopify theme push --only "locales/*.json" matcht ook de schemabestanden zoals locales/en.default.schema.json. Staat zo'n bestand wel in het thema maar niet lokaal, dan verwijdert de CLI het. De thema-editor toont daarna overal "missing translation". Zet daarom alle bestanden die een glob kan raken lokaal neer voordat je met een glob pusht.

Een standaardwaarde in een schema is niet te vertalen

Een sectie met "default": "Waarom je planten koopt bij XXLplant" in het schema toont die tekst zolang niemand de instelling invult. Shopify biedt zo'n standaardwaarde niet aan om te vertalen, dus op de Duitse pagina staat Nederlands. De oplossing is de tekst als echte instelling in het JSON-sjabloon zetten. Dan verschijnt hij als vertaalbaar veld. Bij XXLplant deden we dat op 5 oktober voor vier secties.

De editor en de code schrijven in dezelfde bestanden

Instellingen uit de editor staan in dezelfde JSON-bestanden waar een developer in werkt. Past iemand in de editor een tekst aan terwijl jij lokaal hetzelfde sjabloon bewerkt, dan overschrijft jouw push zijn wijziging. Haal daarom altijd de laatste versie op vlak voordat je pusht, en push per bestand in plaats van het hele thema.

De paginacache verbergt je wijziging

Shopify serveert kale URL's van collecties en producten uit een eigen paginacache, ook als de CDN-header iets anders zegt. Je wijziging staat live, maar de pagina toont een paar minuten de oude versie. Controleer een push daarom met een extra parameter in de URL, zoals ?sort_by=title-descending, die de cache omzeilt.

Een nieuw thema heeft geen koppeling

De koppeling hangt aan één thema. Bouw je een nieuwe versie als kopie en zet je die live, dan is het live-thema niet meer gekoppeld en loopt de geschiedenis in GitHub niet mee. Koppel een nieuwe versie daarom aan een eigen branch voordat je hem publiceert, en voeg die branch daarna samen in je hoofdbranch.

Hoe je branches en thema's indeelt

De werkwijze die we nu aanraden heeft drie lagen. De hoofdbranch is gekoppeld aan het live-thema. Elke grotere wijziging krijgt een eigen branch, gekoppeld aan een eigen ongepubliceerd thema met een eigen voorbeeldlink. Daar test je, daar kijkt iemand anders mee, en pas daarna gaat de wijziging via een pull request naar de hoofdbranch.

Dat levert drie dingen op. Je ziet bij elke fout welke regels veranderden en zet ze met één revert terug. Meerdere mensen en agents kunnen tegelijk werken zonder elkaars werk te overschrijven. En je kunt een nieuwe pagina laten zien aan een klant, terwijl bezoekers nog de oude zien. De vertalingen in negen talen, de 3D-viewer en de plantendokter van XXLplant zijn via de commandoregel en de API in het thema gezet. Wat die onderdelen doen, lees je in Shopify SEO en 3D-modellen met AR in de praktijk.

Voor wie de GitHub-integratie de moeite waard is

Voor een kleine winkel die zelden iets aan het thema verandert, is de editor van Shopify genoeg. Werk je met meer mensen aan je webshop, verkoop je in meerdere talen, of pas je het thema elke week aan, dan betaalt de koppeling zich terug bij de eerste fout die je in een minuut terugdraait. Hoe XXLplant in dertien landen verkoopt, lees je in Shopify Markets: één webshop in dertien landen.

Wil je jouw Shopify-thema aan GitHub koppelen zonder dat de editor ophoudt te werken? Dan zetten we het samen op.