# twilight.json reference (https://docs.salla.dev/twilight/react/guide/twilight-json) 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](https://docs.salla.dev/twilight/react/guide/settings). This page is the lookup. ## Top-level keys [#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-"`. 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 [#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 local theme editor edits every type here. Lists that come from the store (`items` with a `source` of products, categories or brands) and `variable-list` links are picked from your dev store through the preview; when it has none, or can't be reached, the editor offers marked samples instead. Sample products only show how the field works: product blocks fetch products from the store by id, so they can't display them. 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 [#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](https://docs.salla.dev/twilight/react/recipes/add-a-home-block). ## Check the file [#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`: ```bash 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 engine ``` **Errors** 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: ```ts title="scripts/check-manifest.mjs" 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 [#gotchas] * `id` values must be unique **within one list**. The same `id` in `settings` and in a block's `fields` is 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 `source` still needs `"options": []`, as the starter does. ## Next [#next] * [Settings](https://docs.salla.dev/twilight/react/guide/settings): declare a setting and read it. * [Add a home block](https://docs.salla.dev/twilight/react/recipes/add-a-home-block)