Minimum file and folder structure

What is the bare minimum files and structure for a Shopify theme? Online I found documentation for develop theme templates and theme files, but they don't give me a complete picture of minimum file/folder structure that I am looking for. We start with uploading the compressed or zipped theme of an empty folder and continue to resolve the errors of missing templates until there is success.

Here's the first error: missing template layout/theme.liquid.

zip does not contain a valid theme: missing template "layout/theme.liquid"

Now I'm adding an empty theme.liquid file. Success! Going to the Shopify customize screen option, we receive a fail message Theme Preview Error: The layout/theme.liquid file is required to preview this theme.

Theme Preview Error: The layout/theme.liquid file is required to preview this theme.

I added the file, what's going on? Let's add a base html and check if that works.

Here's the code to add to theme.liquid:

<!DOCTYPE html>
<title>Joe Pichardo</title>

<h1>Testing Bootlace theme</h1>


Still, the same error comes up.

I download the theme, but when I extract it, only the config folder appears with settings_data.json with an empty object and settings_schema.json with an empty array. These files compile automatically from Shopify if they are not added. Going to the Edit code settings, there are seven folders I see and assume are required: layout, templates, sections, snippets, assets, config, and locales.

settings_data.json and setting_schema.json only files showing in empty theme

I tried adding them, but the same message appears. Let's add the missing files and folders seen in the links I provided in the intro of this journey, develop theme templates and theme files. Here's the structure now:

  • assets
  • config
    • settings_data.json
    • settings_schema.json
  • layout
    • theme.liquid
    • checkout.liquid (Shopify Plus, must ask support/account manager for file permission)
  • locales
  • sections
  • snippets
  • templates
    • 404.liquid
    • article.liquid
    • blog.liquid
    • cart.liquid
    • collection.liquid
    • gift_card.liquid
    • index.liquid
    • list-collections.liquid
    • page.liquid
    • password.liquid
    • product.liquid
    • search.liquid
    • customers/
      • account.liquid
      • activate_account.liquid
      • addresses.liquid
      • login.liquid
      • order.liquid
      • register.liquid
      • reset_password.liquid

After adding all the files we have partial success! Everything except the theme.liquid is showing up, is it because there are no sections? I add a homepage.liquid file to the sections folder, still the Theme Preview Error persists, but we get closer now with a new error on the sections sidebar This page doesn't have sections, let's keep investigating.

This page doesn't have sections

After a quick Google search, I found documentation for theme.liquid, that mentions the file must have {{ content_for_header }} for Shopify scripts and {{ content_for_layout }} for dynamic content, which should fix our theme preview error. Another great doc I found was index.liquid is our homepage, and it must include {{ content_for_index }} if we want to add sections. That would fix our This page doesn't have sections error. Let's try uploading just the theme.liquid file now that we understand the importance of its contents, pun intended.

Here is the code in our theme.liquid file now:

<!DOCTYPE html>
    <title>Joe Pichardo</title>

    {{ content_for_header }}

<h1>Testing Bootlace theme</h1>

{{ content_for_layout }}


With only uploading the theme.liquid file, here is the result:

Not found 404, The page you were looking for does not exist

An interesting 404 error that I'm assuming comes default with Shopify. Looking at the code editor, I see the theme.liquid file is finally displaying in the layout folder.

Let's add our empty front page file, index.liquid.

Finally! We see our theme.liquid content on the screen. Now we know the minimum structure only includes two files and folders: layout/theme.liquid and templates/index.liquid.

Successful theme upload with only theme.liquid and index.liquid files

Here's the structure:

  • layout
    • theme.liquid
  • templates
    • index.liquid

With only these two files, we have a website with only a homepage, but a website nonetheless.

What happens if we publish the theme with password protection enabled and no password.liquid file?

The result, a default Shopify page to enter the site password:

Password protected website

Next we will start with adding my personal favorite css framework, Bootstrap, to our theme.

Joe Pichardo | Shopify Developer

About Joe Pichardo

Joe Pichardo is a Shopify Developer creating themes and apps to help other programmers succeed on the ecommerce platform.

Having trouble? Ask for help.