Nunjucks Theme API

Version: 1.0.0 (MARKT_NUNJUCKS_API_VERSION) Framework-agnostic Nunjucks engine for MARKT storefronts. Themes use standard Nunjucks (extends, include, macro, for, if) plus the stable context below. For product grids and tags, also read Shortcodes & Tags and Build a Custom Theme. Before shipping a live Nunjucks theme, read Nunjucks Theme Pitfalls (autoescape, Alpine x-data, cartPage, lean cart API, visibility). Legal pages: Policy & Legal Pages — store.policies.* and files privacy-policy.njk / terms.njk / refund-policy.njk.

Architecture

Theme files (.njk, settings.json, assets/)
        │
        ▼
  MarktNunjucksLoader (sandboxed paths)
        │
        ▼
  Extension preprocessors (optional)
        │
        ▼
  Nunjucks compile + render
        ├── MARKT core filters/globals
        └── Extension tags/filters (optional)
        │
        ▼
  HTML (+ SEO/i18n on live requests)

Layer	Location
Core engine	`lib/builder/nunjucks/core/`
Public API	`lib/builder/nunjucks/api/`
Extensions	`lib/builder/nunjucks/extensions/`

Lifecycle

Phase	What happens
Import	ZIP validated; engine detected; `settings.json` merged from templates
Preview	Compiled to RAM cache (content hash + assets + extensions)
Live	Route → `buildMarktStorefrontContext()` → render → SEO/i18n
Publish	Revision hash; HTML cached; assets at `/markt-theme-assets/live/{revision}/`

Context objects (stable v1)

Object	Description
`store`	`id`, `name`, `description`, `url`, `logo`, `favicon`, `stats`, `policies`, `integrations`, `social`
`products`	All catalog products (including group members)
`standaloneProducts`	Products with `groupId == null` — use for main grids
`groups`	Storefront groups (`id`, `name`, `minPrice`, `maxPrice`, `productIds`, …)
`catalogItems`	Mixed catalog: groups first, then standalone (`kind: 'group' \| 'product'`)
`product`	Current product or `null`
`reviews` / `reviewsPaginator`	Feedback
`categories`	Category links
`productsPaginator`	Paginated standalone products (excludes grouped)
`customer`	Logged-in customer or `null`
`invoices`, `tickets`, `ticket`	Customer portal
`currency`, `currencyRates`, `currencySymbols`	Money display
`productUpsells`	Related products
`helpers.components.products.getItemsByIds(items, ids)`	Filter by id/slug
`settings`, `global`	Theme `settings.json`
`templateName`, `templateContent`	Active template + body
`components_order`	Builder component order
`path`, `locale`, `t()`	Routing + i18n
`canonical_url`, `seo_title`, `seo_description`	SEO

Types: lib/builder/nunjucks/api/types.ts

`MarktProduct` (summary)

Typical fields: id, slug, name, description, image, minPrice / maxPrice (not a top-level price), visibility, stock (-1 = unlimited), variants, groupId.

Product groups

Prefer catalogItems / standaloneProducts for homepage grids — never list every products entry as a card when groups exist.
Group members: helpers.components.products.getItemsByIds(products, group.productIds).

On-hold (`visibility`)

Value	In catalog?	Purchase?
`public` / `unlisted`	Yes	Yes
`on-hold`	Yes	No — disable cart / buy; show badge
`private`	Never in payload	—

{% set onHold = product.visibility == 'on-hold' %}
{% if onHold %}
  <button disabled>Unavailable</button>
{% else %}
  <button @click="appCart.add(product.id, variantId, qty)">Add to cart</button>
{% endif %}

Checkout / embed APIs also reject on-hold — UI disable is still required.

Filters

Filter	Example
`assetUrl`	`{{ "pro.css" \| assetUrl }}`
`shopUrl`	`{{ "/cart" \| shopUrl }}`
`apiUrl`	`{{ "v1/cart" \| apiUrl }}`
`imageUrl`	Absolute image URL
`formatPrice`	`{{ 9.99 \| formatPrice("USD") }}`
`formatDate` / `formatDateTime`	Locale dates
`json`	Safe JSON for scripts
`replace`	String replace
`hex_to_rgb`	`{{ "#6366f1" \| hex_to_rgb }}`
`themeColor`	Accent from settings
`ytEmbedLink`	YouTube → embed URL

Tag	Example
`markt_component`	`{% markt_component "navbar" %}`
`markt_snippet`	`{% markt_snippet "meta-tags.njk" %}`

Globals

Global	Example
`range`	`{% for i in range(0, 5) %}`
`formatPrice`	`{{ formatPrice(19.99) }}`

Minimal theme layout

layouts/base.njk
templates/home.njk
snippets/header.njk
macros/button.njk
assets/style.css
settings.json

<h1>{{ store.name }}</h1>
<a href="{{ '/products' | shopUrl }}">Products</a>
<link href="{{ 'style.css' | assetUrl }}" rel="stylesheet" />

{% for product in products %}
  <a href="{{ ('/product/' ~ product.slug) | shopUrl }}">
    {{ product.name }} — {{ product.minPrice | formatPrice(currency) }}
  </a>
{% endfor %}

Cart

Step	Mechanism
Add	`appCart.add(productId, variantId, quantity)` on `#app`
Badge	`appCart.countWithQuantities`
Cart page	`GET /api/v1/cart?storeId=&shopId=&cart=` → `fullCart`
Sync	Response `cart` replaces `appCart` with product cuids

MarktCartItem shape (camelCase):

{
  "productId": "cuid",
  "variantId": "0",
  "quantity": 1,
  "currency": "USD",
  "product": { "name": "…", "slug": "…", "image": "…", "price": 9.99, "url": "…" },
  "variant": { "name": "…", "price": 9.99, "quantityMin": 1, "quantityMax": 10 }
}

Themes with components/cart-page.njk get markt-cart-client injected for quantity/remove/checkout sync.

settings.json

{
  "global": {
    "properties": { "theme_color": "#6366f1" },
    "components": {}
  },
  "templates": {
    "shop": {
      "layout": "master",
      "components": {
        "hero": { "type": "hero", "properties": {} }
      },
      "components_order": ["hero"]
    }
  }
}

Missing template entries are auto-discovered from templates/*.njk.

Extensions (optional)

import { registerNunjucksExtension } from '@/lib/builder/nunjucks/extensions/registry'

registerNunjucksExtension({
  id: 'acme.marketplace',
  name: 'Acme compatibility',
  detect: (files) => Boolean(files['acme.json']),
  preprocess: (source) => source,
  register: ({ env, renderTemplate }) => { /* tags/filters */ },
  enrichContext: (ctx) => ({ ...ctx, acmeData: {} }),
})

Built-in markt.sellauth activates for legacy {% render_component %}, {% render_snippet %}, apiInternalUrl, or schema.json. Native themes use Join Markt tag names only.

Stability

Minor/patch: additive fields/filters/extensions
Major: removing/renaming core context keys, filters, or globals

Validation

npx tsc --noEmit
npm test -- tests/builder

​Nunjucks Theme API

​Architecture

​Lifecycle

​Context objects (stable v1)

​MarktProduct (summary)

​Product groups

​On-hold (visibility)

​Filters

​Tags

​Globals

​Minimal theme layout

​Cart

​settings.json

​Extensions (optional)

​Stability

​Validation