Theme Development
Build custom Liquid themes for Cartly. Understand the three-layer resolver, fork-on-write semantics, section schema, and how the code editor tracks your customizations.
Architecture
Cartly themes use a three-layer file resolver. Every file request — from the storefront renderer or the code editor — is checked in order: (1) DB row (merchant fork), (2) Platform embed FS (current binary bundle at backend/internal/theme/embed/), (3) Boilerplate FS (legacy fallback).
Fork-on-write: no DB row is created until the merchant explicitly saves an edit. Platform updates flow automatically into all unforked stock files on every deploy.
Code Editor Workflow
File tree badges: Synced (stock embed), Custom (merchant forked), New (merchant-created). Filter with All / Modified / Synced chips. To fork: click a Synced file → click Edit file or press ⌘E → confirm in the modal. First save creates the DB row and records the upstream_hash.
Amber Upstream updated banner appears when the platform ships a new embed version of a file you forked. Use View diff (Monaco diff editor with hide-unchanged-regions) or Sync upstream to revert.
Section Schema
Every sections/*.liquid file must end with a {%- schema -%} block. The presets array is required — without it the section is invisible in the + Add panel.
Setting types
| type | Widget |
|---|---|
| text | Single-line input |
| textarea | Multi-line |
| image_picker | Media selector |
| color | Color picker |
| range | Slider (min/max/step) |
| select | Dropdown (options array) |
| checkbox | Toggle |
| url | URL input |
| product | Product typeahead |
| collection | Collection typeahead |
Inline Editing
Add data-cartly-edit="<settingId>" to any element to make it directly editable in the visual editor preview iframe. For block settings also add data-block-id="{{ block.id }}".
API Reference
| Method | Path | Description |
|---|---|---|
| GET | /admin/theme/library/:id/files | List all files with source, badges, upstream_changed |
| GET | /admin/theme/library/:id/files/:key | Get single file including embed_content for diff |
| PUT | /admin/theme/library/:id/files/:key | Create or update (fork) a file — CAS via version |
| DELETE | /admin/theme/library/:id/files/:key | Delete or revert — body: action reverted|deleted |
| GET | /admin/theme/library/:id/sections-source | Bulk sections metadata (DB union embed) |
| GET | /admin/theme/library/:id/events | SSE stream of file-save events |
| POST | /admin/theme/library/:id/preview-token | Generate signed 15-minute preview token |
All /admin/* endpoints require Authorization: Bearer <admin-jwt>. The :key parameter must be URL-encoded, e.g. sections%2Fhero.liquid.