Shopify Theme Development Docs

What it covers

The themes section of shopify.dev explains how Shopify storefronts are built "using Liquid, Shopify's theme templating language, along with HTML, CSS, JavaScript, and JSON". The main areas are:

• Architecture: the folders of a theme (layout, templates, sections, blocks, snippets, assets, config, locales) and how a request becomes a page.
• Online Store 2.0: JSON templates that store which sections a page has, so merchants can add, remove and reorder sections on any page in the theme editor, and the migration guide from older themes.
• Sections and blocks: section schemas, settings, presets and blocks. Newer themes also use theme blocks, reusable blocks that can nest and live in their own folder.
• Liquid and APIs: the Liquid reference, the Ajax API for carts and the Section Rendering API for updating parts of a page.
• Tools: Shopify CLI to create, preview and push themes, GitHub integration, and Theme Check to lint Liquid and catch errors.
• Theme Store: requirements for publishing a theme for sale.

Reference themes: Dawn and Horizon

Dawn was Shopify's first source-available reference theme built for Online Store 2.0, and it is still on GitHub (Shopify/dawn). Horizon is the newer first-party theme family, built around theme blocks. Studying either shows how Shopify intends themes to be structured. Note the Theme Store requirements: themes based on or derived from Horizon are not eligible for Theme Store submission, so read the current rules before you start a theme you plan to sell.

Shopify CLI in practice

shopify theme init clones a starter theme, shopify theme dev uploads a temporary, hidden development theme and gives you a local preview with hot reload, shopify theme push and pull sync files with a store, and shopify theme check runs Theme Check. Development themes work on any store you have access to, and a free development store from the Shopify Partner or developer dashboard is the usual place to practise.

Theme app extensions

Apps should not edit a merchant's theme code. Theme app extensions let an app provide app blocks, which merchants place inside sections, and app embed blocks for things like chat widgets, all managed in the theme editor. For theme developers this means leaving room for app blocks in your sections.

Is it worth your time?

Yes, if you build or customise Shopify stores beyond the theme editor. Many freelance Shopify jobs are "add a section", "change the product page" or "fix the cart drawer", and these docs show the supported way to do each.

Prerequisites and free or paid

HTML, CSS and some JavaScript; Liquid is learned alongside. The docs are free. Practising needs a development store, which is free for Shopify partners and developers; a live store needs a paid Shopify plan.

Common questions

Can I edit a theme in the browser? Yes, in the admin code editor, but work on a duplicate or with the CLI and Git so you can undo changes.