theme.json

theme.json is required, at the theme root. A directory containing one is a theme root, for both publishing and git deploy detection.

theme.json

{
  "name": "Minimal",
  "description": "A clean storefront for digital goods.",
  "long_description": "Longer copy for the marketplace listing page.",
  "author": "ByteSell",
  "author_url": "https://bytesell.io",
  "category": "storefront",
  "tags": ["storefront", "minimal", "dark"],
  "preview_images": ["assets/preview-1.png", "assets/preview-2.png"],
  "thumbnail": "assets/thumb.png",
  "demo_url": "https://demo.example.com",
  "price_cents": 0,
  "currency": "USD",
  "schema": 2,
  "builder": "full"
}

Unknown keys are ignored. A malformed manifest does not fail a publish except where noted below.

Listing fields

These become the theme’s marketplace listing.

Field	Type	Notes
`name`	string	Trimmed. Overrides the name supplied at publish. Falls back to the slug.
`description`	string	Trimmed, empty becomes absent.
`long_description`	string	Listing page copy.
`author`	string	Stored as the author name.
`author_url`	string
`category`	string
`tags`	string[]	Non-strings dropped, each trimmed, empties dropped. A non-array becomes `[]`.
`preview_images`	string[]	Theme-relative paths, resolved to immutable asset URLs.
`thumbnail`	string	Same resolution. Falls back to `preview_images[0]`.
`demo_url`	string
`price_cents`	integer	Negative or non-integer becomes `0`.
`currency`	string

is_free is derived from price_cents == 0 and is not a field you set.

A path in preview_images that is not a real file in the bundle is dropped silently, never rendered as a broken image. If your previews do not appear, check the paths against what you actually shipped.

`schema`

The schema generation your theme is written against. An integer, at least 1. Absent, wrong type, negative or fractional all resolve to 1 rather than failing.

Version	Adds
`1`	Sections, inline `blocks { }`, the nine setting kinds
`2`	Theme-level blocks in `blocks/<name>.slurp`, and `@theme` targeting

The gate is one-directional. A deployment newer than the theme is accepted. A theme declaring a version higher than the deployment supports is rejected:

theme.json declares schema 3, but this ByteSell deployment supports up to 2.
Publishing would silently drop settings this theme declares.
Update ByteSell, or build the theme against schema 2.

`builder`

Which editing surface merchants get. "full" or "simple".

full

Section tree, click-to-select on the canvas, SEO panel, nested block editing. The default.

simple

One scrolling column of forms beside the preview. No section tree, no click-to-select, no SEO panel.

The value is trimmed and lowercased, and anything other than simple resolves to full. A typo cannot make a theme unpublishable. builder is presentation only. Both shells call the same endpoints with the same scopes, and the server does not read this value. It grants and restricts nothing. Use simple for a theme small enough that a section tree adds overhead, such as a link-in-bio layout. See The builder.

`version`

The publish path does not read version. The published version comes from the publish request, or the server bumps the patch of the highest existing clean semver.

Changing version in theme.json does not produce a new version. It is read only by the dashboard when detecting a theme in a connected repository, for display.

File	Required	Malformed
`config/settings_schema.json`	no	Must be valid JSON. Shape is not validated, and a non-array is ignored at merge.
`config/migrations.json`	no	Valid JSON and a valid migration map, or the publish fails.

config/migrations.json renames things across a schema change so merchant content survives:

config/migrations.json

{
  "section_renames": { "Banner": "Hero" },
  "setting_renames": { "Hero": { "title": "heading" } },
  "block_renames":   { "link_item": "link" }
}

setting_renames is keyed by the post-rename section type.

Get started

Build

Ship

Reference

Listing fields

`schema`

`builder`

full

simple

`version`

​Listing fields

​schema

​builder

full

simple

​version

​Related files

Listing fields

`schema`

`builder`

`version`

Related files