twilight.json reference
Every part of twilight.json, the types and formats a setting or field can have, and how to check the file.
Read this when you edit twilight.json by hand and want to know what each key means, or when a setting does not show up in the dashboard. For a first walk-through, start with Settings. This page is the lookup.
Top-level keys
When you publish, the dashboard reads only settings, components, features, support_url and groups. The other keys are for the Salla CLI and the store listing.
| Key | Type | Description |
|---|---|---|
type | "react" | Required by the CLI. Without it the CLI takes the wrong path. The dashboard ignores it. |
name, description | { ar, en } | The theme name and text, per language. |
repository, author_email | string | Where the source lives, and who to contact. |
support_url | string | Where merchants get support. |
features | string[] | Dashboard features to switch on, such as "fonts", "color" or "mega-menu". A home block the platform ships is listed as "component-<name>". A name the dashboard does not know is dropped without an error. |
settings | array | Options merchants can change. |
components | array | Home page blocks merchants can add. |
A setting or a field
Entries in settings, and the fields of a home block, share one shape. The dashboard requires an id and a type. The type must be one of six values, and the publish fails on any other. The format picks the input; leave it out and the type's default is used.
type | Default format | Other formats | Value you read |
|---|---|---|---|
boolean | switch | true or false | |
items | dropdown | dropdown-list, variable-list | The chosen option's value, or a list of them with multichoice |
string | none | text, textarea, hidden, image, url, email, color, icon | Text, or an address for image and url |
number | integer | number, numeric | A number |
collection | collection | A list of items, each made of the nested fields | |
static | none | title, line, description | Nothing: decoration in the dashboard |
The dev settings panel only edits boolean, items/dropdown-list with inline options, and the text formats. It shows the rest as read-only.
Keys an entry can carry:
| Key | Description |
|---|---|
id | Required, unique in its list. The key you read in code. In a home block it may only use letters, digits, -, . and _. |
label, description, placeholder, icon | The text and icon the dashboard shows next to the input. |
value | The default. A boolean for a switch, text for a text field. |
selected | The default choice of a dropdown. |
options | The choices of a dropdown, each { label, value }. |
source | Loads a dropdown's choices from the store: products, brands or categories. Leave options empty. |
required, multichoice | In a home block, each must be true or false. multichoice lets a dropdown pick several values. |
multilanguage | A text field with a value for each language. |
conditions | Shows the field only when another field matches: [{ "id": "active", "operation": "=", "value": true }]. id names the other field. |
fields, minLength, maxLength | For a collection: the nested fields, and how many items are allowed. A collection must have fields. In a home block it must also have whole-number minLength and maxLength. |
The starter also uses labelHTML, variant and item_label. The dashboard reads them; the engine does not.
A home block
Each entry in components is one block. The dashboard requires title, key, path and fields, and the publish fails if one is missing.
| Key | Description |
|---|---|
key | A unique id for the block, usually a UUID. |
title | Name per language, shown in the dashboard. |
path | home. plus the name your component is registered under. Only letters, digits, -, . and _. |
fields | The inputs of the block. Each field id becomes a key on the component's data prop. The dashboard adds hidden key and path fields itself. |
icon | The icon in the block list. Defaults to sicon-wrench-pencil. |
image | A preview image. |
is_default | Set on the starter's standard blocks. The dashboard's settings import does not read it for home blocks. |
A block does nothing until a component is registered for its path. See Add a home block.
Check the file
The engine ships a command, twilight-check-manifest, that reads twilight.json and lists mistakes. The starter runs it as pnpm check:manifest:
pnpm check:manifest # errors fail, warnings are listed
pnpm check:manifest --strict # warnings fail too
pnpm exec twilight-check-manifest path/to/twilight.json # any theme that depends on the engineErrors are things that break the theme or make the dashboard reject it: a missing or wrong type, a type outside the six allowed, a duplicate id, a dropdown with neither options nor a source, a switch whose value is not true or false, a collection without fields, a block missing title, key, path or fields. Warnings are values the check does not recognise, such as a format this page does not list. They may be fine, so check them.
vite dev also prints the errors (not the warnings) when it starts and each time you save twilight.json, at most eight lines at a time.
The same check is available in code, for a test or your own script:
import { validateTwilightManifest } from '@salla.sa/twilight-theme-engine/vite';
const { errors, warnings } = validateTwilightManifest(JSON.parse(text));
// each issue is { path: 'settings[3].id', message: '...' }Gotchas
idvalues must be unique within one list. The sameidinsettingsand in a block'sfieldsis fine.- The check follows the rules the dashboard applies when a theme is published, but not all of them. A clean result is a good sign, not a guarantee.
- A dropdown with
sourcestill needs"options": [], as the starter does.
Next
- Settings: declare a setting and read it.
- Add a home block