Introduction & Theme Development Overview
Welcome to the SitePack Theme Development guide! Whether you are an experienced e-commerce developer or a frontend designer building your first storefront skin, SitePack provides an incredibly fast, secure, and modern platform to realize your designs.
SitePack themes are high-performance frontend skins built on the powerful Twig templating engine. By utilizing a "Skeleton-First" architecture, SitePack removes the typical friction of starting from scratch, giving you a robust, pre-configured base to build upon while maintaining complete creative control.
Architectural Philosophy & Core Concepts
To build great themes on SitePack, it is important to understand the four foundational pillars of our frontend architecture:
1. The Skeleton-First Paradigm
We believe developers shouldn't have to reinvent the wheel for standard e-commerce features. Every SitePack theme begins with the Official Theme Skeleton. The skeleton is not a generic template, but a highly optimized structure containing standard page directories, default base layouts, and ready-to-use snippets for critical pages like:
- Product Details (
templates/product.twig) - Product Listing & Categories (
templates/category.twig) - Shopping Cart Overview (
templates/cart.twig) - Homepage (
templates/index.twig)
This ensures best practices (semantic HTML, accessibility, speed) are baked-in, allowing you to focus your energy on unique design elements, styling, and user experience.
2. High-Performance Template Compiling via Twig
We chose Twig as our exclusive templating engine because it delivers the perfect balance of flexibility, safety, and speed:
- Speed & Efficiency: Twig templates compile directly into highly optimized PHP code, which is then cached. There is no heavy runtime overhead or slow client-side JS rendering bottleneck, resulting in exceptionally high Google Lighthouse / Core Web Vitals scores.
- Security & Sandboxing: Twig is fully sandboxed on our servers. This ensures theme code can never execute dangerous server operations, making the platform secure while giving you comprehensive access to e-commerce data objects.
- Familiarity: If you have developed templates in Liquid, Jinja2, or Blade, you will feel right at home with Twig. Its syntax is clean, logical, and easy to learn.
3. Edge-Optimized Assets
Frontend assets (stylesheets, scripts, images, webfonts) are critical to loading performance. SitePack distributes all static assets via our Global Content Delivery Network (CDN) with automated cache-busting version hashes. Please note that SitePack does not compile SCSS/Sass or compress/minify assets on the fly; developers should provide a completed build with pre-minified CSS in the assets folder.
4. Direct Customization (Theme Settings & Editor)
SitePack themes are highly configurable for end-users. By defining custom input fields (colors, fonts, toggle switches, text regions) directly inside your root theme.json manifest file, you automatically generate a user-friendly customization interface in the SitePack Theme Editor. This empowers merchants to manage their brand assets without touching code.
Key Features at a Glance
As a theme developer, you have access to advanced platform tools to build highly interactive, dynamic, and extensible storefronts:
| Feature | Description | Developer Benefit |
|---|---|---|
Hot Reloading (sitepack theme:watch) | Instant background sync of local workspace files to your development environment. | See template, style, and config changes instantly in the browser upon saving. |
| Modular Layout Snippets | Build modular, reusable template components with simple include directives. | Keep your codebase DRY, clean, and highly maintainable. |
| App Blocks & Hooks | Pre-defined layout zones ({% app_block %}) designed for third-party integrations. | Seamlessly support review widgets, newsletter forms, or marketing apps without breaking layout. |
| Custom Layout Templates | Pre-defined structured schemas in theme.json connected to dedicated custom twig files. | Deliver a headless-like structured editor for marketing pages, landing layouts, and promotion boards. |
| Multi-Language Fallbacks | Clean JSON translation files organized in a smart hierarchy. | Localize themes with regional fallbacks (e.g., nl_be falling back to nl) and parameter variables. |
The Standard Theme Development Workflow
The lifecycle of developing a professional SitePack theme follows a logical and streamlined process:
┌────────────────────────┐
│ 1. INITIALIZATION │ ──> Run 'sitepack theme:init' to download the Skeleton
└────────────────────────┘
│
▼
┌────────────────────────┐
│ 2. LOCAL DEVELOPMENT │ ──> Run 'sitepack theme:watch' & edit files in your IDE
└────────────────────────┘
│
▼
┌────────────────────────┐
│ 3. PREVIEW & TESTING │ ──> View staging build at staging-[subdomain].sitepack.app
└────────────────────────┘
│
▼
┌────────────────────────┐
│ 4. RELEASE & PUBLISH │ ──> Execute 'sitepack theme:publish' to deploy live version
└────────────────────────┘
│
▼
┌────────────────────────┐
│ 5. MONETIZATION │ ──> Set subscription or license fees in Partner Dashboard
└────────────────────────┘
- Initialize: Start by setting up your theme's workspace using our CLI tool.
- Develop: Code templates using Twig, design layout files, add assets, and configure theme settings.
- Preview: Interact with your staging site dynamically. Test across devices and browsers.
- Publish: Deploy your finalized codebase to the platform.
- Monetize: Opt to make your theme private (for specific client stores) or publish it publicly on the SitePack Theme Marketplace to generate recurring revenue.
SEO & AI-Model Optimization Meta-Data
For developers utilizing AI tools (like Copilots or custom GPTs) to write templates or code against the SitePack platform, our documentation is structured with precise API models, complete schema representations, and exhaustive field maps. This ensures AI assistance is highly accurate, generating valid Twig blocks, functions, and config files on the first try.
Ready to Start?
Let's dive into setting up your local environment and initializing your first theme in the Getting Started guide!