Queek docs

How themes work

The theme folder, the kit underneath it, and templates, designs and variants.

The folder

A theme is the theme/ folder: React components and CSS. It holds your layout, header and footer, the page-builder blocks, the store pages, optional shells around the flows Queek owns, plus three files that describe it:

  • manifest.ts — the theme's metadata and the variants each block, header and footer comes in.
  • theme.config.ts — author, tags, categories, and the templates and designs it ships.
  • demo.json — the main demo store: the products, photos and copy the preview renders.

Theme vs kit

The theme renders. The kit (@usequeek/theme-kit) does everything else: data, cart, auth and checkout. Your components read the store through hooks like useProducts, useShop, useCart and useStorefront. You never fetch, never call an API, never write to the kit's stores.

A block, end to end

This is the shape of every data-driven component: read through a hook, link through the kit, render images through the kit, and take every word from t(). It is a trimmed copy of the starter's products block.

theme/blocks/products.tsx
'use client';

import type { JSX } from 'react';
import { Link } from '@usequeek/theme-kit/navigation';
import { Image } from '@usequeek/theme-kit/components/image';
import { useThemeStrings } from '@usequeek/theme-kit/provider';
import { useProducts } from '@usequeek/theme-kit/hooks/use-products';
import { useHref } from '@usequeek/theme-kit/hooks/use-href';
import { formatMoney } from '@usequeek/theme-kit/utils/format';

export function ProductsBlock(): JSX.Element | null {
  const t = useThemeStrings();
  const href = useHref();
  const { products, isLoading } = useProducts({ limit: 8, sort: 'latest' });

  if (!isLoading && products.length === 0) return null;

  return (
    <section aria-busy={isLoading || undefined}>
      <h2>{t('products.title')}</h2>
      <ul>
        {products.map((product) => (
          <li key={product.id}>
            <Link href={href(`/products/${product.slug}`)}>
              <Image src={product.media.thumbnail ?? undefined} alt={product.title} />
              <h3>{product.title}</h3>
              <p>{formatMoney(product.pricing.sale_amount, product.currency)}</p>
            </Link>
          </li>
        ))}
      </ul>
    </section>
  );
}

Locally the hook returns the demo store's products, so the block previews with no API. In production the same code reads the live store. Nothing in the theme changes.

Theme → templates → designs

A theme is the look. A template is one business the theme is dressed as — food, hair, clothes — with that business's own sections. A design is one concrete demo store of a template. A merchant picks one design, and Queek builds their store from its layouts, then fills it with the merchant's own products and photos.

Variants

Each block, header and footer comes in variants: small named designs declared in manifest.ts, each with an id, a label and a one-line purpose. A variant needs a renderer and exactly the fields its component reads. Merchants switch variants in their editor.

Design tokens

Style from design tokens, never fixed sizes: var(--fs-*) for type, var(--space-*) for spacing, var(--radius-*) for corners, var(--image-*) for image sizes. A hard-coded size is a setting that does nothing in the merchant's editor.

Run npm run check at any point: it is the judge of all of the above. The full contract is THEME.md — start with its Templates section for what each design must carry.

On this page