Shopify Theme Directory Structure Explained

The Big Picture: How a Shopify Page is Assembled

Before we look at individual folders, let's understand the architectural concept. A page on a Shopify store isn't a single HTML file. It's dynamically constructed from a hierarchy of components.

This layered approach is what allows a merchant to, for example, add a "Featured Products" section to their homepage without touching any code. They are interacting with the Section layer within the index (homepage) Template.

Here is what this structure looks like in a typical code editor:

Now, let's dive into the purpose of each of these directories. We'll use a fantastic, in-depth video to guide our exploration. It covers the "why" behind the structure, which aligns with your preference for first-principles understanding.

The Core Theme Directories

The video we'll be using provides a comprehensive walkthrough. A key point it makes early on is that Shopify themes have a flat directory structure. You cannot create sub-folders within most of these main directories. This is a platform constraint you must work within.

Now let's break down the role of each directory.

1. layout - The Master Shell

The layout directory contains the master template for your theme. The most important file here is theme.liquid.

• Purpose: It acts as the global shell for almost every page on the store. It contains the <html>, <head>, and <body> tags, and is where you include global assets like your main CSS and JavaScript files.
• Analogy: This is very similar to a _layout.tsx file in Next.js or index.html in a client-side React app. It defines the static frame into which dynamic page content is injected.
• Key Variables:
  • {{ content_for_header }}: Placed within the <head>, this object is critical. Shopify injects essential scripts here, including analytics and scripts required by Shopify Apps.
  • {{ content_for_layout }}: Placed within the <body>, this is the placeholder where the content from your more specific template files (like product.liquid or collection.json) will be rendered.

2. templates - The Page Blueprint

Templates define the content and structure for a specific type of page, like a product page, a collection page, or the homepage (index).

With Shopify's Online Store 2.0 (OS 2.0), there are two kinds of templates:

1. .liquid templates (Legacy): These are files containing Liquid and HTML code. They are less flexible.
2. .json templates (Modern): These are data files that simply list which sections should be rendered on the page. They contain no HTML. This structure is what enables the "Sections Everywhere" feature, allowing merchants to add, remove, and reorder sections on any page, not just the homepage.

The key takeaway is that JSON templates separate content from presentation. The .json file holds the data and a list of section files to use, while the actual markup lives within the individual section files.

3. sections - Configurable Content Modules

Sections are the heart of modern Shopify theme customization. They are reusable modules of content that merchants can add, configure, and reorder directly in the theme editor.

• Purpose: To create modular, customizable components for building pages.
• Analogy: A section is like a React component that comes with its own prop-types definition. The schema (defined in {% schema %} tags) acts as the prop-types, telling Shopify what configuration options (text fields, color pickers, product selectors) to show the merchant in the UI.
• Key Feature: The {% schema %} tag. This is a JSON object within the section's Liquid file that defines the settings a merchant can control.

4. snippets - Reusable Code

Snippets are small, reusable pieces of Liquid code. They help you keep your code DRY (Don't Repeat Yourself).

• Purpose: To extract repetitive code into a single file that can be included in multiple places.
• snippets vs. sections: This is a critical distinction.
  • Sections are for modular content and are visible and configurable by the merchant in the theme editor.
  • Snippets are for modular code and are invisible to the merchant. They are a tool for developers to organize their code better. A snippet might be rendered inside a section.
• Usage: You use the {% render 'snippet-name' %} tag to include a snippet. You can also pass parameters to them, similar to passing props to a component.

5. assets - Static Files

This is the most straightforward directory. It holds all your theme's static assets.

• Purpose: Stores CSS, JavaScript, images, and font files.
• Referencing: You must use the asset_url Liquid filter to generate the correct URL for a file in this directory. For example: {{ 'theme.css' | asset_url | stylesheet_tag }}. This ensures Shopify serves the asset from its optimized CDN.

Supporting Directories

Two other folders complete the picture:

• config: This holds the global configuration for the theme.

  • settings_schema.json: Defines the structure of the options you see under "Theme settings" in the customizer (e.g., global colors, typography choices).
  • settings_data.json: Stores the merchant's saved values for the settings defined in settings_schema.json. You typically don't edit this file by hand.

• locales: This directory is for internationalization (i18n). It contains JSON files with translations for all the text strings in your theme, allowing the store to be displayed in multiple languages.

Conclusion

You now have a complete map of a Shopify theme's architecture. This structure is designed to create a powerful separation of concerns:

• layout: The global presentation shell.
• templates: The blueprints for different page types, primarily pointing to sections.
• sections: The merchant-configurable content blocks that make up the pages.
• snippets: The reusable developer components for keeping code clean.
• assets: The home for all static files like CSS, JS, and images.
• config: The hub for global theme settings.

Understanding this hierarchy is the single most important step to moving from simply editing Liquid to architecting professional, maintainable Shopify themes.

In our next lesson, we will get our hands dirty. Now that you understand the map, we'll set up a local development environment using the Shopify CLI. You'll pull down a theme to your own computer, connect it to your development store, and start navigating these very folders yourself.