Theme Anatomy

A Tanqory theme is a standard React + Vite app built on @tanqory/theme-kit. You mostly work in two folders: sections/ (React components) and templates/ (JSON that composes sections into pages).

Project structure

my-theme/
├── sections/       React components — one file = one section (the core of a theme)
├── templates/      JSON that composes sections into pages (index, product, cart…)
├── layouts/        Layouts that wrap every page
├── config/         Theme configuration
├── assets/         Static assets
├── components/     Shared components used by sections
├── lib/            Helpers + bundled sample data
├── locales/        Translations
├── main.tsx        Boot entry (don't edit)
├── index.html
├── tanqory.config.ts
├── vite.config.ts
└── package.json    Depends on @tanqory/theme-kit + react

Available scripts (run by the CLI, but usable directly):

pnpm dev        # vite dev server on :4321
pnpm build      # production build → dist/
pnpm typecheck

Sections

A section is a React component plus a schema describing its editable settings. Define it with defineSection:

// sections/MyPromo.tsx
import { defineSection, type SectionProps } from '@tanqory/theme-kit'

export function MyPromo({ attributes }: SectionProps) {
  const heading = attributes.heading as string
  return <div className="promo">{heading}</div>
}

export default defineSection({
  name: 'my-promo',          // the id templates reference
  title: 'My Promo',
  category: 'block',
  attributes: {
    heading: { type: 'text', default: 'On sale now', label: 'Heading' },
  },
  component: MyPromo,
})

Common attribute types: text, richtext, boolean, number, image, select. Each attribute you declare becomes an editable setting in the visual editor and a value templates can set.

Templates

A template is JSON that lists section instances for a page. type is the section's name; settings are its attribute values; area places it (header, template, or footer); blocks are repeatable child items.

// templates/index.json
{
  "sections": [
    { "type": "header",   "id": "header",  "area": "header" },
    {
      "type": "my-promo",
      "id": "promo-1",
      "area": "template",
      "settings": { "heading": "50% off this week" }
    },
    { "type": "footer",   "id": "footer",  "area": "footer" }
  ]
}

The starter ships templates for every storefront page: index, product, collection, cart, blog, article, account, contact, 404, and more.

Data

Sections read live storefront data (products, collections, cart, customer) through @tanqory/theme-kit. When you run tanqory theme dev, that data comes from your dev store; with --mock it comes from bundled fixtures in lib/.

Tips

• Start by copying an existing section from sections/ (e.g. the slideshow or product grid) and adjusting it — don't start from a blank file.
• Keep sections small and composable; build pages by arranging them in templates.
• Run pnpm typecheck before pushing.