Themes
How the multi-theme system works and how it fits into the QUANTM7 platform.
QUANTM7 stores can run multiple themes at the same time. Each theme is a full set of design settings, homepage sections, and custom code. Merchants switch between themes without any code changes or deploys.
Architecture
Every store has at least one theme. Each theme has two rows in the database: a draft and a published copy. The storefront always reads the published row for the active theme.
store_themes
UNIQUE (store_id, theme_name, is_draft)
is_active BOOLEAN -- one theme per store
theme_name VARCHAR -- user-friendly labelThis constraint allows unlimited themes per store, each with its own draft/published pair. Only one theme can be active at a time.
Theme engines
Each theme is built on one of three engines:
| Engine | Tier | Description |
|---|---|---|
| Spark | Free | 11 color presets, full section support, custom CSS/JS |
| Glass | Premium | Frosted glass aesthetic, floating nav, custom glass tint |
| Pebble | Premium | Rounded, organic feel, pebble-style nav |
All three engines share the same 24 section types. The engine controls the header, navigation, footer, and announcement bar rendering.
Theme lifecycle
Create → Edit (draft) → Publish → Activate → Live on storefront- Create. Pick a name, engine, and whether to clone from the active theme.
- Edit. The visual editor loads the theme's draft. All changes stay in the draft.
- Publish. Copies draft to published. If this is the active theme, the storefront updates.
- Activate. Sets this theme as the live theme. Requires a published row. The storefront revalidates.
Service layer
The theme-service.ts file handles all multi-theme operations:
| Function | Purpose |
|---|---|
listThemes | List all themes for a store, grouped by name |
createTheme | Create a new inactive draft |
activateTheme | Set a published theme as live |
deleteTheme | Remove a theme (blocks if active) |
duplicateTheme | Copy a theme's draft to a new name |
renameTheme | Change a theme's display name |
publishTheme | Copy draft to published row |
All functions accept storeSlug as the first argument. The optional themeName parameter defaults to the active theme when omitted, so existing code that was written before multi-theme support continues to work.
Editor integration
The visual editor reads ?theme=<name> from the URL to load a specific theme. When a store has two or more themes, a theme name dropdown appears in the toolbar. Switching themes navigates to a new URL and reloads the theme data.
The storefront iframe also receives the theme name as a URL parameter, so the server renders the correct theme for the preview.
Revalidation
When the active theme is published, the storefront revalidates automatically. Activating a different theme also triggers revalidation. Non-active themes can be published without affecting the live storefront.
Database migration
The multi-theme schema is activated by running docs/SQL_MIGRATION_MULTI_THEMES.sql. This migration:
- Adds
theme_name,is_active, andcreated_from_templatecolumns - Changes the unique constraint from
(store_id, is_draft)to(store_id, theme_name, is_draft) - Names all existing themes "Spark" and marks them as active
- Adds a partial index on
is_active = truefor fast storefront reads