---
url: https://docs.youcan.shop/themes/architecture.md
---
# Theme architeture

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](#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](/themes/layouts)     | The base file wrapping every page, holding common elements like the header and footer. |
| 2      | [Template](/themes/templates/overview) | Determines what is rendered on a given page, and where.                              |
| 3      | [Section](/themes/sections/overview)   | Reusable, customizable areas of a page that can be added to JSON templates.          |
| 4      | [Block](/themes/blocks)       | Reusable, customizable units that sellers can add, reorder, and remove within a section. |
| 5      | [Snippet](/themes/snippets)   | Small reusable Liquid or HTML fragments included from a section or layout.            |

## Directory structure

Themes must adhere to the following structure

```bash
.
├── 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:

```json
{
  "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](/themes/filters/assets/assetUrl) Liquid filter to reference an asset within your theme.

### `config`

The `config` directory contains [config](/themes/config/overview) files which defines the [settings](/themes/settings/overview) in the Theme settings area of the theme editor and their values.

### `layout`

The `layout` directory contains the [layout](/themes/layouts) 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](/themes/locales/overview) 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](/themes/sections/overview) files

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

### `snippets`

The `snippets` directory contains Liquid [snippet](/themes/snippets) 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](/themes/templates/overview) 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.