Architecture
How the application turns a template into a page
| # | Step | What happens | Source |
|---|---|---|---|
| 1 | render | index.html is rendered by TemplateEngine.render() with the placeholder data (see Data). | server.js:735 |
| 2 | strip-document | <!DOCTYPE>, <html>, <head>…</head> and <body> tags are removed: your markup becomes the body content of a page the application builds. | server.js:740 |
| 3 | sanitize-html | sanitizeHtml(): removes script, iframe, object, embed, base, applet, frame, frameset, meta, link, style elements, every on* event attribute, javascript:/vbscript:/data:text/html URLs, cross-origin form actions, srcdoc and style attributes with external url(). | server.js:743 |
| 4 | image-urls | <img src> values are normalised: image/x → /image/x, external URLs → /img-proxy?url=… | server.js:744 |
| 5 | wrap | The application adds the <head> (approved CDN CSS, fonts, core.css, kit.css when enabled, branding tokens, your stylesheet, approved CDN scripts) and the closing scripts (your script.js, then engine.js, then the config JSON). | server.js:680 server.js:708 |
Scripts load in this order: approved CDN scripts (deferred) → templates/<name>/script.js (deferred) → /assets/storefront/engine.js (deferred) → <script id="love-config-json" type="application/json"> config. The page is served with this Content-Security-Policy:
default-src 'self'; script-src 'self' https://code.jquery.com https://cdn.jsdelivr.net https://cdnjs.cloudflare.com; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://cdnjs.cloudflare.com; font-src 'self' data: https://cdnjs.cloudflare.com; img-src 'self' data: blob: https:; connect-src 'self' https://cdn.jsdelivr.net https://cdnjs.cloudflare.com https://code.jquery.com; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; frame-src 'none'; worker-src 'self'; manifest-src 'self'
Which template is active
The active template is found by matching activeThemeId against the folder name, theme.json slug or theme.json id, then activeThemeName against folder name, slug or name. If nothing matches, the first installed template (alphabetically) is used.
- Copy the template folder to <app>/templates/<name>/ (name: letters, digits, "-" and "_").
- Load it: restart the application, or (signed in as admin) POST /api/templates/reload {"templateName":"<name>"}.
- Activate it: set pos_setting.theme.activeThemeId to the folder name / theme.json slug / theme.json id, or (admin) POST /api/templates/switch {"theme":"<name>"}.
server.js:1210 server.js:1219 template-engine.js:606
How the SDK is built
| Part | What it does |
|---|---|
Built-in storefront runtimeruntime/ | The parts of the store a template meets: its template engine (template-engine.js), sanitizers (security.js), page-head builder (store/theme-assets.js), the public browser files every shopper downloads (engine.js, core.css, kit.css, fonts), the store's templates as starters, and the template rules discovered from the store (contract.json). No server, database, schema, payment or configuration code. |
Template ruleslib/contract | Discovered from the store's source (template-engine.js, server.js, security.js, store/theme-assets.js, store/urls.js, public/assets/storefront/engine.js, public/assets/storefront/core.css, public/assets/storefront/kit.css) and templates when the runtime is built: files, placeholders, directives, the template.json schema, engine hooks, routes, sanitizer rules, fonts, endpoints. |
Core librarylib/ | HTML and CSS parsers that keep source offsets, safe structural edits, the validator, the project model, packaging. Shared by the CLI and the Studio; no UI code. |
Preview serverlib/standalone | The SDK's own storefront server. It renders your template with the store's engine and sanitizers and the same page head, scripts and configuration, and answers every call the storefront engine makes — stores, catalogue, cart, coupons, delivery, checkout, accounts, orders, wishlist — from JSON demo data. Its responses were checked field by field against the real store's. |
Test runnerlib/tests | Runs the preview runtime and drives Chrome/Edge/Chromium through the DevTools protocol (no Puppeteer/Playwright needed). |
CLIbin/template-sdk.js | Every command is a thin wrapper around the library. |
Studiolib/studio | A local web app (127.0.0.1 only) served by the SDK and opened in a Chrome/Edge app window or your browser. Its preview is the preview server's page shown through the same origin with a small bridge script added for selection and error reporting. |
Isolation and security
- The preview server listens on 127.0.0.1 only, holds the demo shop in memory (nothing is written to disk, nothing connects to a database or a payment provider) and starts afresh when the demo data changes.
- The Studio API requires a per-session token, checks the Host header (DNS-rebinding protection), refuses paths outside the project, inside
.template-sdk/node_modules/.git, or reached through a symbolic link that leaves the project. - Saves are atomic (write to a temporary file, then rename) and refuse to overwrite a file that changed on disk since it was opened.
- The preview applies the store's own sanitizers and security headers (CSP), so a template can do no more in the Studio than in the store.