> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytesell.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Project structure

> The theme root, meaningful directories, and the published bundle.

## 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.

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

## Directories

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

| Path                          | Contents                                                                |
| ----------------------------- | ----------------------------------------------------------------------- |
| `theme.json`                  | The manifest. Required. See [theme.json](/themes/reference/theme-json). |
| `pages/**/*.slurp`            | URL routes. See [Pages and routing](/themes/pages).                     |
| `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:

```json theme={null}
"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.

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

## Committed and generated files

<Tabs>
  <Tab title="Commit">
    * Everything under the theme root, including `css/theme.css`
    * `theme.json`
    * `dev-globals.json`, if used. It is excluded from build output
      automatically.
  </Tab>

  <Tab title="Ignore">
    * `dist/`, the local build output
    * `node_modules/`
    * Dot-directories. `.git` and `.github` are dropped from every bundle before
      it is read.
  </Tab>
</Tabs>

## 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](/themes/reference/limits) for file counts and size ceilings.

## Next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/themes/quickstart">
    Build a theme end to end.
  </Card>

  <Card title="Pages and routing" icon="signs-post" href="/themes/pages">
    Route resolution and special pages.
  </Card>
</CardGroup>