Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 61 ยท Getting Started

The Theme File Structure

A tour of the Shopify theme folders: layout, templates, sections, blocks, snippets, assets, config and locales, what each holds, and how they load together.

Every Shopify theme is a folder with the same eight top-level directories. Shopify only looks for code in those places, so knowing what goes where is the single most useful thing a new theme developer can learn. Once you can open a theme and say "this belongs in a section, that belongs in a snippet", you can find your way around any theme in minutes.

This lesson describes each folder, shows how they fit together when a page renders, and mentions the limits you should know about. The folder tree here is real; the code that walks and checks a tree at the end is a stand-in written in JavaScript, because the real Shopify validators run on Shopify's side.

The eight folders

TEXT
theme/
  assets/      CSS, JavaScript, images, fonts
  blocks/      reusable theme blocks (newer themes)
  config/      theme-wide settings
  layout/      page wrappers, such as theme.liquid
  locales/     translation files
  sections/    page parts with their own settings
  snippets/    small reusable Liquid pieces
  templates/   one template per page type

Shopify does not allow other top-level code folders, and it does not support nested subfolders inside most of them. The theme editor and Shopify CLI both expect this exact shape.

flowchart TD
  L["layout/theme.liquid"] --> T["templates/product.json"]
  T --> S1["sections/main-product.liquid"]
  T --> S2["sections/related-products.liquid"]
  S1 --> B["blocks/*.liquid"]
  S1 --> SN["snippets/price.liquid"]
  L --> A["assets/base.css"]
  S1 -.reads.-> C["config/settings_data.json"]
  S1 -.reads.-> LO["locales/en.default.json"]

A layout wraps a template; the template lists sections; sections use blocks and snippets; assets, config and locales support everything.

layout/

Layouts wrap every page. The main one, layout/theme.liquid, contains <html>, the <head>, the header and footer sections and the placeholder where each page's content appears. A theme can have more layouts, for instance password.liquid for the storefront password page. A template can pick another layout, or none at all. See Layouts and theme.liquid.

templates/

One file per page type: index, product, collection, cart, page, blog, article, search, 404, list-collections, gift_card.liquid, password. In modern themes these are JSON templates (product.json), which list sections and their order. Customer account pages live in templates/customers/ (such as login, register, account, order, addresses). Metaobject pages live in templates/metaobject/. Alternate templates use a suffix, for example product.featured.json or page.contact.json, which the merchant can assign per product or page.

A few templates are still Liquid files: gift_card.liquid and robots.txt.liquid, for instance. Details in JSON Templates and Online Store 2.0.

sections/

A section is a Liquid file with markup and a {% schema %} block describing its settings and blocks. Sections are what the merchant moves around in the editor. Sections can also be groups defined in JSON, such as header-group.json, which let you place the same sections in different layouts. You will build them in Building a Section.

blocks/

Files in blocks/ are theme blocks: reusable pieces (a button, a text heading, a product card) that many sections can accept, and which can nest inside each other. Older themes did not have this folder; their blocks were defined inside each section's schema. See Blocks and Theme Blocks.

snippets/

Snippets are small Liquid files that you include with {% render 'name' %} from other files. They have no schema and no editor settings. Use them for repeated markup such as a price, an icon or a product card. Snippets cannot be added by merchants in the editor, which is the main difference from sections. See Snippets and the render Tag.

assets/

Static files: stylesheets, scripts, images, fonts, SVGs. This folder is flat, with no subfolders, so names like component-cart.css and global.js carry the structure. You reference assets with the asset_url filter, which returns a CDN address. Liquid can run inside files with a .liquid extension (theme.css.liquid), but modern themes avoid that and use CSS variables instead (see CSS for Themes).

config/

Two JSON files control theme-wide settings:

  • settings_schema.json describes the settings the merchant sees under "Theme settings" (colors, fonts, social links).
  • settings_data.json stores the values the merchant has chosen, and it also holds the current content of the templates in some themes and presets.

settings_data.json is edited by the theme editor, so be careful about overwriting it. Global Theme Settings explains both files.

locales/

Translation files named after language codes: en.default.json for the store's default language, fr.json, de.json, and so on. A file ending in .schema.json (en.default.schema.json) translates text that appears in the editor, such as setting labels. In Liquid you read translations with the t filter. See Translations, Markets and Localization.

How the folders load together

When Shopify renders a page, the order is predictable:

  1. Layout. It starts with the layout file (theme.liquid, unless the template names another).
  2. Template. The layout calls content_for_layout. At that point Shopify renders the template for the page type.
  3. Sections. For JSON templates, each section in the template's order is rendered, passing in its settings and blocks.
  4. Snippets and blocks. As sections run, {% render %} tags pull in snippets, and block files render inside their parent.
  5. Assets. The <head> and the end of the <body> reference files in assets/ through asset_url. The browser requests those afterward.
  6. Config and locales. settings and the t filter are available throughout.

Sections that are not part of a template but sit in the layout (like the header) are included with {% sections 'header-group' %} or {% section 'header' %}.

Stand-in: walk a virtual file tree

The real theme folder lives on Shopify's servers and your disk. This stand-in uses a list of paths to check the shape of a theme: valid top-level folders, nested folders where Shopify does not allow them, and missing required files. The rules are simplified versions of what Theme Check and the upload process enforce.

JS Stand-in: validate a theme folder shape

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Which files serve which request?

A useful skill is predicting which files a request touches. The next stand-in does that for a made-up product page. It does not run Liquid, it only follows the references. Real theme tooling (Theme Check, the editor) builds a similar dependency map.

JS Stand-in: follow references between files

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The footer is listed as unused only because our toy layout forgot to reference it. In a real theme theme.liquid includes the footer group, and Theme Check would flag a section nobody uses.

Limits and rules to remember

Shopify sets limits that can change over time, so treat the numbers below as approximate and confirm them in the current developer documentation before relying on them:

  • A JSON template can contain a limited number of sections (the documented cap is in the dozens), and a section can have a limited number of blocks (50 is the common maximum for the max_blocks setting).
  • Theme size and file count are limited. Very large themes slow uploads and the editor.
  • File names use lowercase letters, digits, hyphens and underscores. Keep them short and descriptive.
  • Only one asset can share a name; there are no subfolders in assets, so a prefix convention (component-, section-, template-) keeps order.

A common naming pattern in Dawn is component-*.css for shared pieces and section-*.css for section-specific styles. You will see it in Exploring Dawn.

Do not put secrets (API keys, passwords) in any theme file. Everything in assets/ is public, and Liquid output is visible in the page source. Read more in Security in Themes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which folder holds small reusable Liquid pieces that have no editor settings?

    Snippets are included with the render tag. They have no schema, so merchants cannot add them in the editor. Sections do have a schema and can be placed by merchants.
  2. 2. Where do you store the CSS and JavaScript files of a theme?

    The assets folder holds static files. It is flat, so use name prefixes to organize them.
  3. 3. What is the difference between settings_schema.json and settings_data.json?

    settings_schema.json defines what the merchant can configure. settings_data.json holds the current values, and the editor writes to it.
  4. 4. In what order does Shopify start rendering a product page?

    The layout is the outer wrapper. It places the template through content_for_layout, and sections and snippets are rendered when they are referenced.

Summary

  • A theme has eight folders: assets, blocks, config, layout, locales, sections, snippets and templates.
  • Layouts wrap templates; JSON templates list sections; sections use blocks and snippets.
  • Assets are flat, snippets have no schema, and settings_data.json holds merchant choices.
  • Locales hold translations, and a .schema.json file translates editor text.
  • Limits exist on sections, blocks and size; check current documentation for exact numbers.

Next, read a real theme in Exploring Dawn, the Reference Theme.