Quickstart

A theme with one editable section, rendered locally and deployed to a store.

Install the CLI

Install Slurp

cargo install slurp-compiler slurp-dev-server

This installs two binaries: slurp for build and validate, and slurp-dev for the preview server.

slurp --version

Create the theme

Create the directories

mkdir -p my-theme/site/{pages,layouts,sections,templates,css}
cd my-theme

site/ is the theme root. The parent directory holds build tooling, which is not published.

Write the manifest

site/theme.json identifies the directory as a ByteSell theme.

site/theme.json

{
  "name": "My Theme",
  "description": "A starter storefront.",
  "author": "Your Name",
  "category": "storefront",
  "schema": 2,
  "builder": "full"
}

schema: 2 enables theme-level blocks and @theme targeting. builder selects the merchant’s editing surface; full is the default.

Add a layout

Pages share this shell. Script and stylesheet URLs come from platform rather than literal paths.

site/layouts/base.slurp

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>${ storefront.name }</title>
    <link rel="stylesheet" href="/css/theme.css" />
    <link rel="stylesheet" href="${ platform.fonts_css }?family=inter:400,700" />
    <script defer src="${ platform.sdk }"></script>
    <script defer src="${ platform.cart }"></script>
    <script defer src="${ platform.alpine }"></script>
  </head>
  <body>
    <slot />
  </body>
</html>

Do not hardcode those script URLs. They are versioned by the platform, and a literal path is frozen at the version it names. See Platform assets.

Add an editable section

The section { } frontmatter becomes a form in the builder.

site/sections/Hero.slurp

---
section {
  name: "Hero"
  max_per_page: 1
  settings {
    heading:  text = "Welcome"
    subtitle: text = "Digital goods, delivered instantly."
    accent:   color = "#6366f1"
  }
}
---
<section style="border-top: 4px solid ${ section.settings.accent }">
  <h1 data-bs-edit="heading">${ section.settings.heading }</h1>
  <p data-bs-edit="subtitle">${ section.settings.subtitle }</p>
</section>

data-bs-edit makes an element editable in place. Its value is the settings key written back to.

Add the page

A page places {sections} without naming which sections go there. The merchant controls that, starting from the defaults in the next file.

site/pages/index.slurp

{layout "@layouts/base"}
  <main>
    {sections}
  </main>
{/layout}

An element form, <layout src="@layouts/base">, also exists. Prefer the block form. The element form builds its node with no head slot, so a {head} block inside it renders in the body, where those tags have no effect.

Add default content

templates/index.json supplies the content a store starts with when the theme is installed. Its filename matches the page.

site/templates/index.json

{
  "sections": [
    {
      "id": "hero",
      "type": "Hero",
      "settings": { "heading": "My store" }
    }
  ]
}

type matches sections/Hero.slurp. Omitted settings fall back to the schema defaults.

Write the stylesheet

site/css/theme.css

body { font-family: Inter, system-ui, sans-serif; margin: 0; }
section { padding: 4rem 1.5rem; }
h1 { font-size: 2.5rem; margin: 0 0 .5rem; }

base.slurp links this file, so it must be present in the bundle. Publishing rejects a theme whose linked stylesheet is missing. Most themes generate it with Tailwind and commit the output.

Render it

slurp build has no store to query, so the platform URLs are supplied directly:

dev-globals.json

{
  "platform": {
    "sdk": "http://localhost:5004/_bs/r/2/sdk.js",
    "cart": "http://localhost:5004/_bs/r/2/cart.js",
    "alpine": "http://localhost:5004/_bs/r/2/alpine.js",
    "fonts_css": "http://localhost:5004/_bs/fonts.css"
  },
  "storefront": { "name": "Dev Store", "currency": "USD" }
}

slurp build --input site --output dist --globals dev-globals.json

Without --globals, every ${ platform.* } resolves to nothing and the page renders <script src="">. The page loads, appears close to correct, and has no JavaScript at all.

dist/pages/index.html is the full document, with ${ storefront.name } and every ${ platform.* } resolved:

dist/pages/index.html

<!doctype html><html lang=en><meta charset=utf-8><title>Dev Store</title>
<link href=/css/theme.css rel=stylesheet>...<body><main></main>

Then serve it:

slurp-dev --source-dir site --theme-dir dist --port 3500 --globals dev-globals.json

Use the slurp-dev binary, not slurp dev. The subcommand forwards only --port and --fixtures, so it cannot pass --globals, and the platform URLs resolve empty.

`{sections}` in a static build

<main></main> above is expected. Section content lives in the merchant’s database and slurp build has no store to read, so {sections} renders nothing. templates/index.json is applied when a store installs the theme, not at build time. To render a section template, pass a section object directly. It is an ordinary context key:

preview-globals.json

{
  "platform": { "...": "as above" },
  "section": {
    "id": "hero",
    "type": "Hero",
    "settings": { "heading": "My store", "accent": "#6366f1" }
  }
}

slurp build --input site --output dist --globals preview-globals.json

dist/sections/Hero.html

<section style="border-top: 4px solid #6366f1"><h1 data-bs-edit=heading>My store</h1>...

This path does not merge. The template sees exactly what is written, so defaults are not filled in, numbers are not clamped and richtext is not sanitized. Use it to check markup, not to verify schema behaviour.

slurp build writes an HTML file for every .slurp outside components/ and layouts/, which accounts for dist/sections/Hero.html. Those are local build output and are not part of the published bundle.

Deploy to a store

Themes deploy from GitHub. There is no upload.

Push the repository

Commit everything, including site/css/theme.css.

Connect it

In the dashboard, open My Store, connect the GitHub repository and select the branch. ByteSell reads the tree, locates the directory containing theme.json and validates it before accepting the connection.

Push again

Every push to that branch redeploys. Check the deploy status, then set the theme live.

Two connection failures are common, and both indicate the wrong directory: no theme.json manifest at the theme root and theme.json found, but no .slurp files in this folder - is it the right one?.

Pages and routing

Dynamic routes and special pages.

Sections and blocks

Nested blocks, zones and default content.

Store data

The storefront object and fetching products.

Publishing

Versioning, the schema gate, and every rejection.

Get started

Build

Ship

Reference

Install the CLI

Create the theme

Render it

`{sections}` in a static build

Deploy to a store

Next

Pages and routing

Sections and blocks

Store data

Publishing

​Install the CLI

​Create the theme

​Render it

​{sections} in a static build

​Deploy to a store

​Next

Pages and routing

Sections and blocks

Store data

Publishing

Install the CLI

Create the theme

Render it

`{sections}` in a static build

Deploy to a store

Next