Theme organization

Directory structure

A PrestaShop theme is a set of files which you can edit in order to change the look of your online shop.

Here are a few important tidbits:

  • All themes have their files located in the /themes folder, at the root of PrestaShop’s folder.
  • Each theme has its own sub-folder, in the main themes folder.
  • Each theme is made of template files (.tpl), image files (.jpg, .png and such), one or more CSS files (.css), and usually JavaScript files (.js).
  • Each theme has a preview.png image file in its folder, enabling the shop-owner to see what the theme looks like directly from the back office, and select the theme appropriately.

The best way to learn how to create a theme for PrestaShop is to dive into the Classic Theme.

Here is its organization, which is explained further below.

  .
  ├── CONTRIBUTING.md
  ├── README.md
  ├── _dev
  │   ├── css
  │   │   └── ...
  │   ├── js
  │   │   └── ...
  │   ├── package.json
  │   └── webpack.config.js
  ├── assets
  │   ├── css
  │   │   ├── ...
  │   ├── img
  │   │   └── ...
  │   └── js
  │       └── ...
  ├── composer.json
  ├── config
  │   └── theme.yml
  ├── modules
  │   └── ...
  ├── plugins
  │   └── ...
  ├── preview.png
  └── templates
      ├── _partials
      │   └── ...
      ├── catalog
      │   ├── _partials
      │   │   └── ...
      │   ├── listing
      │   │   └── ...
      │   └── ...
      ├── checkout
      │   ├── _partials
      │   │   └── ...
      │   └── ...
      ├── cms
      │   ├── _partials
      │   │   └── ...
      │   └── ...
      ├── contact.tpl
      ├── customer
      │   ├── _partials
      │   │   └── ...
      │   └── ...
      ├── errors
      │   ├── ...
      │   └── static
      │       └── ...
      ├── index.tpl
      ├── layouts
      │   ├── layout-both-columns.tpl
      │   ├── layout-content-only.tpl
      │   ├── layout-error.tpl
      │   ├── layout-full-width.tpl
      │   ├── layout-left-side-column.tpl
      │   └── layout-right-side-column.tpl
      ├── page.tpl
      └── wrapper.tpl

The folders are used this way:

/_dev/
Contains the raw development files for your SCSS, JavaScript and image assets.
They are to be compiled using Webpack, and turned into production assets.
/assets/
Contains the production assets, compiled by Webpack from the _dev files.
/config/
Contains configuration file. By default, it only has the theme.yml file.
/modules/
Contains either theme-specific modules, or the theme’s version of native modules’ template files.
For instance, the themes/classic/modules/ps_categorytree/views/templates/front/ps_categorytree.tpl file replaces the Category module’s own modules/ps_categorytree/views/templates/front/ps_categorytree.tpl
/plugins/
Your custom smarty plugins
/templates/
Contains the template files themselves (.tpl), mostly in contextual subfolders (catalog, checkout, cms, etc.).
The _partials folder contains “partial templates”, which means parts that can used by / included into several templates: header.tpl, breadcrumb.tpl, footer.tpl, etc.
This prevents redundant code blocks, and makes themes easier to maintain.

Required templates and libraries

Required templates

When you install/enable a theme, PrestaShop checks if the theme is valid: it looks for the theme.yml file (and checks its content), its declared compatibility, and the existence of some files.

There is a list of files that need to exists, even if they’re empty. Please see dedicated documentation to know what makes a theme valid.

It could be that you’ve built some sort of groundbreaking theme and it doesn’t exactly work like the Classic Theme does. For instance, if you don’t have a product page, then you don’t need the product.tpl file. In that case, you just have to create an empty product.tpl file. Be nice to the next developer and add a comment indicating where the code related to products can be found ;)

Required libraries

jQuery v3.5 is loaded by the core (bundled in core.js) file.

Read more about assets management.