Theme Directory Structure & File Mapping
A SitePack theme follows a structured, standard directory layout. This directory conventions-based system ensures that the SitePack compilation engine can instantly locate, resolve, and render your templates, modular snippets, layouts, translations, and dynamic configurations.
By keeping the folder names consistent, SitePack can optimize asset delivery and inject the correct e-commerce data models depending on the page a customer is visiting.
High-Level Folder Hierarchy
When you initialize a theme using sitepack theme:init, the local project workspace is automatically hydrated with the following directory tree:
your-theme-directory/
├── assets/ # Public frontend static resources
│ ├── css/ # Pre-minified storefront CSS stylesheets
│ ├── js/ # Frontend JavaScript scripts
│ ├── img/ # Theme images and static graphics
│ └── fonts/ # Web font files (woff, woff2)
├── layouts/ # Root wrapper shells (HTML structures)
│ └── base.twig # The core base layout
├── snippets/ # Reusable template snippets (DRY blocks)
│ ├── header.twig # Site-wide top header element
│ ├── footer.twig # Site-wide bottom footer element
│ └── product-card.twig # Standard catalog item list-card
├── templates/ # Standard e-commerce view templates
│ ├── index.twig # Homepage template
│ ├── product.twig # Single product details template
│ ├── category.twig # Category / Product list template
│ ├── cart.twig # Shopping cart overview template
│ ├── account.twig # Customer portal / Orders template
│ ├── page.twig # Standard rich-text content page
│ ├── blog.twig # Article collection listing page
│ ├── article.twig # Single blog post content template
│ └── 404.twig # Page Not Found template
├── translations/ # Multi-lingual locale definitions
│ ├── en.json # English localization keys
│ └── nl.json # Dutch localization keys
└── theme.json # Mandatory theme manifest metadata
Detailed Directory Breakdowns
/assets
The assets directory contains all static client-side resources required to style and animate your theme.
/css: Contains.cssfiles. SitePack does not compile SCSS/Sass or compress/minify CSS files on the fly. Developers must supply their final, completed build with pre-minified CSS directly inside this folder./js: Pure or compiled JavaScript files. Keep interactive logic (such as cart count updates or gallery sliders) structured here./img&/fonts: House your logos, background SVG vectors, fallback loaders, and web font formats (woff,woff2).- Note on Performance: All static assets are automatically edge-cached and globally distributed via the high-speed SitePack CDN during staging and production builds. They utilize automated URL hash-versioning to eliminate client-side caching delays. Read the full Assets Guide.
/layouts
Layouts act as the HTML boilerplate wrapper shells for your entire store.
base.twig: The main layout file that other templates extend. It contains structural outer HTML tags (<!DOCTYPE html>,<html>,<head>,<body>). It includes global headers, imports essential styles via helper functions (sitepack_head()), sets up analytics scripts, declares app injection blocks, and defines the content insertion region.- Template Extension: Storefront template files extend this base structure:
{% extends 'layouts/base.twig' %}
/snippets
Snippets are highly modular, self-contained template segments meant to be included in other layouts or pages. This keeps your codebase DRY (Don't Repeat Yourself) and highly maintainable.
header.twig: The main site navigation header snippet.footer.twig: The site footer snippet.product-card.twig: A single product list representation used on collection listings, search results, and recommended product carousels.- Inclusion Syntax: Reusable snippets are imported using Twig's
includestatement:{% include 'snippets/product-card.twig' with { 'product': item } %}
/templates
The templates folder contains the specific view designs for each page type. Each template is loaded automatically by the SitePack routing engine when a customer visits the matching URL. SitePack injects context-specific data structures into these templates automatically:
| File Name | Storefront Page | Primary Injected Objects & Context |
|---|---|---|
index.twig | Homepage | General site configurations, global settings, recommended arrays. |
product.twig | Single Product Details | Injects the fully populated product object (ProductApiModel). |
category.twig | Collection / Category List | Injects the current category details and an array of matching products. |
cart.twig | Shopping Cart Overview | Injects current line items, quantity adjustments, and pricing totals. |
account.twig | Customer Profile & Orders | Injects customer authentication data and previous order lists. |
page.twig | Standard Content Pages | Injects basic static title and rich-text body fields. |
blog.twig | Blog List View | Injects arrays of recent articles, category lists, and author profiles. |
article.twig | Single Blog Article | Injects the active article model, metadata, and body content. |
404.twig | Page Not Found Error | General fallbacks and navigation links. |
/translations
SitePack themes support full multi-lingual localization.
- Contains JSON translation dictionary files (e.g.,
en.json,nl.json,de.json). - Important Rule: File names MUST be written in lowercase, representing either the base language (
en.json) or region-specific configurations (nl_be.json). SitePack utilizes an intelligent hierarchical resolution fallback during language lookup. Read the Translations Guide.
The Root Manifest: theme.json
The root of your theme workspace must always contain the theme.json manifest. This file acts as the registration registry for the SitePack compiler, detailing the theme's name, active version, author profile, custom schemas, and headless-like custom template blueprints. All Customizer settings and schemas are configured directly inside this file.
Now that you understand the directory layout of your theme, learn how to configure the root manifest in the theme.json Reference Guide!