Project structure

The theme root

The theme root is the directory containing theme.json. Every published path is relative to it. The repository as a whole is not the theme. The first-party themes place it at site/:

my-theme/
  package.json          build scripts. Not published.
  styles/app.css        Tailwind source. Not published.
  dev-globals.json      local dev only. Not published.
  dist/                 build output. Not published, not committed.
  site/                 the theme root. This is what is published.
    theme.json
    pages/
    layouts/
    components/
    sections/
    blocks/
    templates/
    config/
    css/theme.css
    assets/

A directory holding only .slurp files is a subfolder of a theme, not a theme root. Git deploys locate candidate roots by theme.json and reject a repository with none.

Publishing dist/ produces a bundle whose paths are all wrong. dist/ is the local preview target. The publish bundle is the theme root.

Directories

Paths outside this table are static files, stored and served as-is.

Path	Contents
`theme.json`	The manifest. Required. See theme.json.
`pages/*/.slurp`	URL routes. See Pages and routing.
`layouts/*.slurp`	Targets for `{layout "@layouts/base"}`.
`components/*/.slurp`	Targets for `using "@components/Card"`.
`sections/*.slurp`	Editable sections. The type is the filename stem.
`blocks/<name>.slurp`	Theme-level blocks. The type is the filename stem.
`templates/*/.json`	Default content for a new install.
`config/settings_schema.json`	Theme-wide settings. Optional.
`config/migrations.json`	Rename map for schema changes. Optional.
`css/theme.css`	The compiled stylesheet. Required if a template links it.
`assets/`, `img/`	Static files, served by content hash.

Compiled CSS

The CSS build must output inside the theme root, and the output is committed:

"build:css": "tailwindcss -i styles/app.css -o site/css/theme.css --minify"

Publishing rejects a bundle whose templates link a root-relative stylesheet the bundle does not contain:

layouts/shell.slurp links stylesheet "/css/theme.css" but no "css/theme.css" is
in the bundle (run the theme CSS build, e.g. `npm run build:css`, before
publishing)

Without this check the failure is silent: the theme publishes, and every store using it renders unstyled HTML.

Only literal root-relative href values ending in .css are checked. A CDN link or an href containing ${ } is not verified.

Committed and generated files

Commit
Ignore

Everything under the theme root, including css/theme.css
theme.json
dev-globals.json, if used. It is excluded from build output automatically.

dist/, the local build output
node_modules/
Dot-directories. .git and .github are dropped from every bundle before it is read.

Path rules

A path that violates any of these fails the publish, naming the file:

Non-empty, at most 300 characters
No leading /, no backslashes, no //, no trailing /
No segment that is empty, ., .., or starts with ~
Printable ASCII or spaces only

See Limits for file counts and size ceilings.

Quickstart

Build a theme end to end.

Pages and routing

Route resolution and special pages.

Get started

Build

Ship

Reference

The theme root

Directories

Compiled CSS

Committed and generated files

Path rules

Next

Quickstart

Pages and routing

​The theme root

​Directories

​Compiled CSS

​Committed and generated files

​Path rules

​Next

Quickstart

Pages and routing

The theme root

Directories

Compiled CSS

Committed and generated files

Path rules

Next