Skip to main content

Shopify Theme Development Guide (Online Store 2.0)

  • November 2, 2026
  • 9 min read
  • By CYPHEX
Shopify Theme Development Guide (Online Store 2.0)
Illustrative animation with example data

If you run a store and need to decide between a premium theme, a customised one and a fully custom build, this guide is for you. It also gives technical leads a working picture of how Shopify theme development is organised today, so they can brief a developer or review someone else’s work. By the end you should know what Online Store 2.0 changed, what lives where in a theme, how a safe workflow looks, and what to ask for at handover.

What Online Store 2.0 changed

Before Online Store 2.0, only the home page was truly flexible. A merchant could move sections around there, and nowhere else. Developers were hard-coding product and collection layouts in Liquid files, so any layout change meant a code change.

The current model fixes that with a few moving parts.

JSON templates. A page template, such as the product page, is a JSON file that lists sections and their order. Shopify’s architecture docs describe these as wrappers for sections. The code sits in the sections, the JSON just arranges them.

Sections on every page. Because templates are JSON, a merchant can add, remove and reorder sections on any page type that uses one. Section groups do the same for the header and footer areas.

Blocks. Inside a section, blocks are the repeatable pieces: a slide, a tab, an icon with a caption. Shopify now also has theme blocks. These are block files in a /blocks folder, so they can be reused across sections and even nested inside other theme blocks. A section accepts them by listing "@theme" in its schema, and a block needs at least one preset to show up in the editor’s block picker. One catch from the theme blocks docs: a section uses either its own local blocks or theme blocks, not both. Older themes will not have any of this, so ask what a theme supports before you buy it.

App blocks. Apps can ship app blocks that a merchant drops into a section from the editor. Sections need an @app entry in their schema to accept them. The practical gain is clean installs and clean removals, because the app does not rewrite your theme files.

How a theme is organised

A theme is a folder, and the folder names tell you most of what you need. This is the layout from the architecture docs.

FolderWhat goes there
layout/The page shell. theme.liquid must exist and wraps every page.
templates/One file per page type, mostly JSON. Also customer pages and metaobject pages.
sections/Editable building blocks, plus section groups.
blocks/Theme blocks, shared across sections.
snippets/Small reusable Liquid pieces. Merchants never see them in the editor.
assets/CSS, JavaScript, images. A file ending in .liquid gets limited Liquid access.
config/settings_schema.json (what can be set) and settings_data.json (what was chosen).
locales/Translation files for theme text.

A rule of thumb that saves arguments: if the merchant should be able to move or edit it, make it a section or block. If it is a repeated technical detail, make it a snippet.

Liquid in five minutes

Liquid is Shopify’s template language and it runs on Shopify’s servers before the page reaches the browser. That means it can show a price but cannot react to a click. For anything interactive you still need JavaScript.

You will see three things. Objects print data ({{ product.title }}), tags control flow ({% if %}, {% for %}) and filters change output ({{ product.price | money }}).

{% comment %} Show a sale badge only when a compare-at price exists {% endcomment %}
{% if product.compare_at_price > product.price %}
  <span class="badge">Sale</span>
{% endif %}

Liquid is also where many stores quietly lose speed. Shopify’s own performance guidance singles out nested loops as the most common cause of slow server response, and says to read metafields outside loops and to limit how many products or variants you fetch. Our Liquid speed guide goes further. The Liquid reference lists every object and filter.

Buy, customise or build?

This is the decision most owners actually face, and it deserves a straight answer: start with the least custom option that does the job.

Premium themeCustomised themeCustom theme
What it isOff the shelf, configured in the editorA premium or free theme plus code and new sectionsBuilt to your design and content model
Good fitNew or small stores with standard needsEstablished brand with a few distinctive featuresUnusual buying journey, tight performance targets, complex content
TimeShortestMiddleLongest
CostLowest up frontMiddleHighest, plus ongoing upkeep
Main riskLooks like many other storesTheme updates collide with your editsYou own every bug and every update

We are not giving price or hour ranges on purpose. The few you will find online are unsourced, and the real number depends on how many templates, custom sections and integrations you need. Get a written scope instead, and compare quotes on the scope, not the total.

Skip the custom build if the gap is one feature. An app block or a single new section is cheaper and easier to hand on. Also skip it if your catalogue and branding are still shifting month to month, because you will pay twice. If you are weighing Liquid themes against a separate front end altogether, read headless Shopify vs traditional Liquid before deciding.

Customising a theme without trapping yourself

Add new sections and snippets rather than editing the theme’s core files, so a vendor update does not wipe your work. Keep a short change log of every edited file and why. Put extra content into metafields and metaobjects instead of burying it in the template. And never experiment in the live theme.

Shopify CLI, Theme Check and a safe workflow

Shopify CLI is the official command line tool for themes. shopify theme dev gives you a local preview with hot reload against a store’s real data. shopify theme push and shopify theme pull sync files, shopify theme init starts a theme, and shopify theme check runs Theme Check, the linter for Liquid and theme files. Treat Theme Check errors as blockers before anything is published.

A detail that catches people out: development themes are temporary and hidden, and per the docs they are deleted after seven days of inactivity. Your Git repository is the source of truth, not the store. The CLI works with Shopify’s GitHub integration if you want a branch tied to a theme.

A workflow that holds up:

  1. Keep the code in Git, in a repository the owner controls.
  2. Work on a development theme or an unpublished duplicate.
  3. Run Theme Check, then test on a real phone, not only a browser window.
  4. Share the preview with the owner and collect feedback in one place.
  5. Publish at a quiet hour and keep the previous theme unpublished as your rollback.
  6. After publishing, test checkout, forms, cart and tracking events again.

Performance rules that matter in a theme

Shopify’s performance best practices are specific, and .

  • Do not lazy-load the main image that appears first on screen. Give it fetchpriority="high" and use a real <img> rather than a CSS background.
  • Use image_url and image_tag, which produce srcset and dimensions for you.
  • Remove scripts nobody needs, defer the rest, and load heavy code only when someone interacts.
  • Fonts cause layout jumps. Keep families and weights few, or use system fonts.
  • Apps are the usual culprit. Remove leftovers, reserve space for app content with app blocks and a minimum height, and avoid “speed” apps that only game Lighthouse. More in third-party app bloat.

The target is the Core Web Vitals pass marks at the 75th percentile: LCP 2.5 s or less, INP 200 ms or less, CLS 0.1 or less. Core Web Vitals in plain English explains how to read your own numbers.

Accessibility is part of the build

Check keyboard use of menus, filters, the cart and any dialog, with a visible focus outline. Check colour contrast against WCAG, label every form field, keep heading levels in order, and make sure cart changes and errors are announced to screen readers. Retrofitting this after launch costs more than building it in. Legal duties differ by country, so check yours.

Theme handover checklist

Ask for every item below when an agency or freelancer delivers a theme.

  • Source code in a Git repository you own, with a README
  • A list of every customised file and the reason
  • Theme Check run with no errors
  • Notes and screenshots for each custom section, block and setting
  • A list of installed apps, which ones touch theme code, and how to remove them
  • Mobile and performance results from before and after
  • Accessibility test notes
  • Checkout, forms and tracking tested after publishing
  • The previous theme kept as an unpublished rollback
  • Domain, store and app accounts held in the owner’s name
  • An agreed plan for updates and fixes after launch

Frequently Asked Questions

How is a Shopify theme different from an app?

A theme controls how the storefront looks and is structured. An app adds a function such as reviews or subscriptions, and can show its content through an app block. Most stores use both.

Will I lose content when I change themes?

Products, collections and pages stay put. Layout choices and theme settings do not transfer automatically, so budget time to rebuild the layout and test each template.

Is a custom Shopify theme always faster?

No. Speed comes from image handling, script weight, Liquid efficiency and apps. A lean premium theme can beat a heavy custom one.

Do I need Shopify Plus to build a custom theme?

No, themes can be developed on standard plans. Check Shopify’s plans for what each tier adds beyond that.

Can I build a theme myself without being a developer?

You can configure a theme in the editor without code. Real theme development needs Liquid, HTML, CSS and JavaScript plus Git, and a mistake on a live theme costs sales.

Planning a budget for theme work? See what drives Shopify theme customization cost.

Conclusion

For most stores, Shopify theme development should begin small: a good premium theme, then targeted customisation, and a custom build only when the experience truly differs from what themes offer. Whatever route you take, insist on Git, Theme Check, a rollback plan and a handover pack. If you would like help with this, CYPHEX can plan and deliver it for you, with one project lead as your contact. You can also read about our Shopify services.

Stock photography provided by Pexels under the Pexels License.

Want your online store to sell more?

We can review your store and show you what to fix first to turn more visitors into buyers.

Comments

  1. Loading comments...

Leave a comment

Selling online?

Turn more visitors into orders

A faster, clearer store with better product pages and checkout. We handle Shopify and WooCommerce from setup to growth.

Step 1 of 3

Tell us what you need

Three quick steps. We reply within one business day.

What do you need help with? Pick all that apply