Every RAXXO section is a tracked Liquid file, never a customizer edit, across 100+ custom sections
One drag-and-drop change in the theme customizer once bled into every new page for months before anyone noticed
Code review catches a bad section before it ever reaches a live storefront, a customizer click does not
The discipline scales past one person because the file itself is the record, not someone's memory of what they clicked
The Problem With Editing a Live Theme By Hand
The Shopify theme customizer is built to feel safe. You drag a section, adjust a setting, hit save, and the page updates immediately. Nothing about that flow warns you that the change you just made now lives only inside Shopify's database, disconnected from anything you can diff, review, or roll back with a single command. For a store with three sections and one template, that gap barely matters. For a studio running more than a hundred custom Liquid sections across several product lines, it is a slow-motion problem waiting to surface.
I learned this the hard way, not through a hypothetical but through a real default template that picked up stray settings from an About page and quietly carried them onto every new page created afterward. Nobody set out to break anything. Someone made a reasonable edit in the customizer, it saved fine, the page looked right, and the mistake only became visible months later when a completely unrelated page inherited content that made no sense on it. That is the nature of customizer drift. It does not announce itself. It waits for the next person to build on top of the broken assumption.
Once I traced that back to its root, the fix was not a patch to one template. It was a rule: the customizer is read-only from my side. Every section that ships on a RAXXO storefront exists first as a .liquid file in the repository, and the customizer only ever reflects what that file already says. If a setting needs to change, the file changes, gets reviewed, and gets pushed. The live theme is a rendering of the code, never the other way around.
That distinction sounds small until you picture the alternative. Without it, the true state of a storefront is scattered across two places at once, a database of customizer settings and a folder of files, and the two can silently disagree with each other for weeks before anyone opens the right page to notice. With the rule in place, there is exactly one place the truth lives, and everything else is just a rendering of it. I would rather spend an extra minute committing a change than spend an afternoon later trying to figure out which of two disagreeing sources is actually correct.
Code as the Single Source of Truth
Treating sections/ and the newer theme-2026/sections/ directories as the actual source of truth sounds obvious once you say it out loud, but it changes daily habits more than people expect. Every section follows a strict naming convention, section-[page]-[name].liquid, so I can tell what a file does and where it belongs without opening it. CSS classes carry a shared prefix to avoid clashing with anything the theme ships with by default. None of that structure exists in the customizer. It only exists because the files enforce it, and files are the thing I actually read before anything goes live.
This matters most when I am moving fast. A one-person studio does not have a second engineer to catch a mistake before it ships, so the review step has to happen somewhere, and it happens in the diff. When I open a pull request against my own repository, I am reading the exact change that is about to go live, line by line, the same way I would read a change to any script that handles pricing or checkout. A customizer session gives you none of that. You either remember what you changed or you do not, and six months later, memory always loses.
There is a sequencing rule that comes out of the same instinct: upload a new section file first, wait for Shopify to register its schema, and only then upload the template that references it. Batch both together and Shopify silently drops settings the schema has not caught up to yet, which produces a page that looks fine at a glance and is quietly missing configuration underneath. That failure mode only shows up if you are watching closely, which is exactly why the order matters more than it seems like it should.
What Breaks When the Discipline Slips
The retired theme is the clearest example I have of why this rule is not optional. It exists purely as a rollback target now, kept around until its sunset date and otherwise untouched. Because it predates the current discipline, pushing its section files to a live store carries real risk, since the two theme trees have drifted apart in ways that are not obvious from a filename alone. The rule that solved this was simple in hindsight: sync scripts refuse to push a section tree that does not match the theme currently published. It sounds like an obvious safeguard. It only became a rule after a near miss made clear how easy the mistake would be without it.
That is the pattern with almost every rule I have added to this workflow. None of them came from reading a best-practices article. They came from something going slightly wrong, getting traced back to its cause, and getting turned into a check that makes the same mistake structurally harder to repeat. A verified theme ID before any push. A template suffix required on every new page, enforced by the page creation script rather than left to memory. A grep check after creating a page to confirm it did not silently inherit content from an unrelated template. Every one of these exists because the customizer, or a rushed manual step, let something through once.
I have written before about the accessibility pass every RAXXO section gets before it ships, and the parallel is direct. Accessibility checks and source-of-truth discipline are both about refusing to trust "it looked right when I clicked save" as a substitute for an actual, repeatable check. A section that passes an accessibility pass in a file I can re-run against the next hundred sections is worth more than a page that happened to look correct once in the customizer.
Why This Scales Even Though I Work Alone
The obvious objection to all of this is that a one-person studio does not need process built for a team. I would argue the opposite. Process built for a team assumes someone else will catch your mistake. Process built for one person has to assume nobody will, which means the checks have to be structural rather than social. A rule that lives in a script, a naming convention, or a required field on an API call does not depend on me remembering it on a tired Tuesday evening. A habit I am supposed to just recall does.
This is also why the design system that makes five RAXXO tools feel like one studio and the source-of-truth rule reinforce each other. A shared visual language only stays shared if the thing enforcing it is a file everyone, including future me, has to go through. The moment any part of that language lives only in a customizer setting somebody clicked once, it becomes invisible to the next change and the whole system starts drifting without anyone deciding it should.
The version control history is the part I lean on most, more than any single rule. Every section change has an author, a timestamp, and a diff. When something looks wrong on the live site, I do not have to guess when it changed or what changed alongside it. I open the log for that file and the entire history of every edit is right there, in order, with the exact lines that moved. A customizer gives you the current state and nothing else. Code gives you the current state and everything that led to it, which is the difference between fixing a symptom and understanding the actual cause. I also wrote about the docs page I write before I touch the code, and the same logic applies there: writing the plan down first, in a file, makes the plan something I can check my work against later instead of something I half remember.
None of this makes me faster in the moment. A customizer click is quicker than opening an editor, writing a change, and pushing it through review, and there is no version of this workflow where I pretend otherwise. What it buys back is the time I would otherwise spend months later, staring at a page that looks subtly wrong, trying to reconstruct a decision I have no record of making. I would rather pay that cost upfront, every time, in small amounts, than pay it once, unpredictably, in a much larger amount when a customer notices before I do.
Bottom Line
The Shopify customizer is convenient precisely because it hides the cost of a change until later. Code as the source of truth does the opposite: it makes every change visible, reviewable, and reversible the moment it happens, which costs a small amount of friction upfront in exchange for never having to reconstruct what happened after the fact. For a studio running more than a hundred sections with no second engineer to catch a mistake, that trade is not close. The rule is simple to state and easy to break under pressure, which is exactly why it has to be enforced by the tooling itself rather than by good intentions. Every section ships as a file first. The customizer only ever shows what that file already says.
This article contains affiliate links. If you sign up through them, I may earn a small commission at no extra cost to you. (Ad)
Top comments (0)