1. Home
2. Themes
3. Key Concepts
4. Architecture

Theme architeture

Last updated Oct 8, 2026 View as Markdown

A theme is a structured collection of code that determines a storefront's looks and features. Theme code must adhere to a standard directory structure for it to be valid. Each theme directory will contain template and configuration files, as well as any other assets a theme may need (e.g. scripts, images, etc..).The end goal is to give sellers and theme builders full control over storefronts, allowing them to create unique user experience that could serve to distinguish them from other YouCan stores.

Number	Component	Description
1	Layout	The base file wrapping every page, holding common elements like the header and footer.
2	Template	Determines what is rendered on a given page, and where.
3	Section	Reusable, customizable areas of a page that can be added to JSON templates.
4	Block	Reusable, customizable units that sellers can add, reorder, and remove within a section.
5	Snippet	Small reusable Liquid or HTML fragments included from a section or layout.

Directory structure

Themes must adhere to the following structure

.
├── assets
├── config
├── layout
├── locales
├── sections
├── snippets
└── templates

Any directories or subdirectories, that were not listed above, are not supported.

JSON files in these directories, and the JSON in a section's {% schema %}, can contain // and /* */ comments and trailing commas.

Required files

A theme must contain these files:

• layout/theme.liquid
• templates/index.json
• templates/product.json
• templates/collection.json
• templates/list-collections.json
• templates/page.json
• templates/cart.json
• templates/search.json
• templates/thankyou.json
• templates/upsell.json

A theme upload without one of these files is rejected. You cannot delete them in the code editor or with theme dev.

File checks

Each theme file is checked when you save it. If the file has an error, the save is rejected.

A theme upload is checked the same way, file by file, before any file is saved. If one file has an error, the upload is rejected and you get the errors of all files.

Directory	Check
layout, snippets	Liquid syntax
sections	Liquid syntax and the {% schema %} tag
templates	JSON, and the sections, blocks and settings that the template uses
config	JSON, the settings schema and the setting values
locales	JSON objects of strings, with keys made of letters, digits, _ and -

If a save is rejected, you get a 422 with the list of errors:

{
  "errors": [
    {
      "file": "snippets/card.liquid",
      "line": 3,
      "key": null,
      "message": "Unknown tag snippet",
      "severity": "error"
    }
  ]
}

• line is the line of the error, or null when the line is not known.
• key is the path of the setting or schema field with the error, or null.
• severity is error or warning. You can save a file that has only warnings.

In the code editor, errors are marked on their line while you type.

assets

The assets directory contains assets used in a theme, including images, JavaScript, and CSS files.

Use the asset_url Liquid filter to reference an asset within your theme.

config

The config directory contains config files which defines the settings in the Theme settings area of the theme editor and their values.

layout

The layout directory contains the layout files for a theme, through which template files are rendered.

Info

Note that a theme.liquid file is required in the layout directory.

The directory was previously named layouts. That name still works, but it is deprecated.

locales

The locales directory contains the locale files for a theme, which are used to both provide translated content but also provide a translated settings in the theme editor,.

sections

The sections directory contains all the sections files

These Liquid files allow you to create reusable modules of content that can be customized by sellers. They can also include blocks which allow sellers to add, remove, and reorder content within a section.

snippets

The snippets directory contains Liquid snippet files that host reusable snippets of code that can be rendered anywhere in your theme, and are invisible to sellers in the theme editor.

templates

The templates directory contains a theme’s template files, which control what's rendered on each type of page.

You can use the template to add functionality that makes sense for the page type. For example, you can add a product reviews section to a product template.