Template files
The template folder
templates/<name>/ inside the application (one folder per template)
- Name rule:
^[a-zA-Z0-9_-]{1,64}$server.js:301 - Files the loader reads:
.html,.css,.js— top-level files only (sub-folders are not read by the template engine) template-engine.js:76 - Any other file in the template folder (for example logo.png at the top level) is not served by the application.
Files
| File | Required | Role | Description | Source |
|---|---|---|---|---|
template.json | yes | config | Configuration. A folder without a readable template.json is skipped by the loader ("Error loading template"). | template-engine.js:68 template-engine.js:74 |
index.html | yes | markup | The page markup rendered by the template engine. The loader accepts a template without it but logs "will render empty" and the storefront has no content. | template-engine.js:81 template-engine.js:92 |
styles.cssor style.css | no | styles | Template stylesheet, served sanitized at /templates/<name>/styles.css and linked after the shared styles. style.css is accepted as an alternative name (styles.css wins on /styles.css, style.css wins on /style.css; the page links /style.css). | server.js:1084 |
script.js | no | script | Template script, served sanitized at /templates/<name>/script.js and loaded (deferred) BEFORE the shared engine, so it can define window.StorefrontTheme. | server.js:810 |
theme.json | no | meta | Optional installation metadata (id, slug, name, version, previewImage) used to match the store's configured theme to this folder. | template-engine.js:88 |
image/ | no | assets | Images served at /image/<path> for the ACTIVE template (sub-folders allowed). | server.js:1103 |
image/
See Assets.
theme.json
Optional installation metadata. The application reads it (if present) to match pos_setting.theme.activeThemeId / activeThemeName to this template and to report the installed version. It does not affect styling.
| Key | Type | Default | Status | Description |
|---|---|---|---|---|
| id | string | read | Platform template id (e.g. "TPL-…"). activeThemeId may match it. template-engine.js:589 template-engine.js:615 | |
| name | string | read | Display name. activeThemeName may match it. template-engine.js:591 template-engine.js:616 | |
| slug | string | read | Slug. activeThemeId may match it; the admin "switch" stores it as activeThemeId.^[a-zA-Z0-9_-]{1,64}$template-engine.js:590 template-engine.js:615 | |
| version | string | read | Installed version (wins over template.json version). server.js:378 server.js:1231 | |
| previewImage | string | "" | read | Preview image URL shown in the admin template list. template-engine.js:594 |
| sourceUrl | string | "" | not read | Not read by the application. |
| installedAt | string | "" | not read | Not read by the application (written by the platform installer). |
| description | string | "" | not read | Not read by the application. |