Theme SDK
`@poltura/theme-sdk` is the public contract between a Poltura theme and the storefront that runs it: typed modules for authoring elements, reading store data and drawing every commerce feature.
On this page
@poltura/theme-sdk is the public contract between a Poltura theme and the storefront that runs it: typed modules for authoring elements, reading store data and drawing every commerce feature.
Importing
Every name is imported from its module, @poltura/theme-sdk/<module>. There is no root import and no deep import, and no name is exported from two modules, so auto-import always picks the right one.
import { defineSection, field } from '@poltura/theme-sdk/elements';
import { useCart } from '@poltura/theme-sdk/cart';The package holds declarations only. The storefront provides the implementation at runtime, so a theme never bundles SDK code.
Kinds of export
| Kind | Name shape | What it is |
|---|---|---|
| Hook | useX | State and actions. The logic runs on the host and returns declared types only. |
| Part | <Feature><Piece>, such as CartLine | Markup only, styled by tokens, className and classes. Parts never fetch data. |
| Default | <Feature>, such as VariantPicker | The complete feature, built from its parts and hook. The storefront draws it when a theme ships nothing for the feature. |
| Definer | defineX | Authoring calls the theme build reads statically. |
| Function | camelCase verb | A pure helper without React. Rare. |
| Constant | camelCase object or UPPER_CASE value | Catalogue values, so themes never write magic strings. |
| Type | PascalCase | Declared in the package and documented property by property. |
Every feature follows the same pattern: a headless hook, parts that draw it and, for component-level features, a complete default. A theme can use the default, restyle it, or rebuild the feature from the hook and the parts.
One way to do each thing
- Settings arrive already coerced and translated: element settings as the typed
settingsprop, theme settings fromuseThemeSettings(), child blocks fromuseChildBlocks(). - Prices are drawn by the
priceparts from aPriceView. Any other amount goes throughuseFormat().money(). - Data comes from named domain hooks that take one object parameter and return one result shape.
Versions
This is theme API v1, and the package major is the theme API version: SDK 1.x is theme API v1. A minor release adds exports or optional fields; only a new theme API version, released as SDK 2.0.0, removes or changes one. A theme written against one version keeps working on every later minor release of the same major.
Modules
| Module | Import | Purpose |
|---|---|---|
| elements | @poltura/theme-sdk/elements | Authoring: define and override sections and blocks, fields, slots, inline editing and child blocks. |
| layout | @poltura/theme-sdk/layout | Layout primitives and section chrome: containers, stacks, rows, grids and section frames. |
| sections | @poltura/theme-sdk/sections | Complete defaults of the platform's section types, for a theme override to wrap or delegate to. |
| settings | @poltura/theme-sdk/settings | Theme settings and the settings of a template's own section. |
| i18n | @poltura/theme-sdk/i18n | Translations, theme texts, the store's languages and the one formatter. |
| store | @poltura/theme-sdk/store | The store: identity, contact, company, brand, social links, market and features. |
| data | @poltura/theme-sdk/data | Store reads: products, categories, collections, attributes, product types and the content pages and posts a setting points to, each one named hook with one result shape. |
| product | @poltura/theme-sdk/product | Products, variants, options, availability, specifications, reviews, the product page view and the buy box. |
| price | @poltura/theme-sdk/price | Money, prices and price access: what a visitor may see and on which tax basis. |
| listing | @poltura/theme-sdk/listing | Collection, category and search listings: product cards, filters, sort and paging. |
| cart | @poltura/theme-sdk/cart | The cart: its lines, totals, codes and gift cards, the state and actions the cart hook returns, and the cart page's parts. |
| checkout | @poltura/theme-sdk/checkout | Checkout parts a theme may place outside checkout, such as the accepted payment methods. |
| customer | @poltura/theme-sdk/customer | The signed-in shopper: customer, addresses, orders, the account area and the sign-in forms. |
| search | @poltura/theme-sdk/search | Storefront search: the query, live results, suggestions and featured products. |
| chrome | @poltura/theme-sdk/chrome | The header, footer and promo bar and their pieces: brand, user menu, switchers, mobile menu and colour mode. |
| navigation | @poltura/theme-sdk/navigation | Store menus, the category and page tree, mega menu panels and breadcrumb trails. |
| routing | @poltura/theme-sdk/routing | Links, the router, page params and the merchant's site pages. |
| media | @poltura/theme-sdk/media | Images, videos, placeholders, media library files and theme assets. |
| forms | @poltura/theme-sdk/forms | Store forms: the merchant's published forms, the newsletter sign-up and the contact form. |
| content | @poltura/theme-sdk/content | Merchant content: blog posts, legal documents, the FAQ, guides, rich text, Markdown and the contact page. |
| consent | @poltura/theme-sdk/consent | Cookie consent: the shopper's choice and the actions that record it. |
| inbox | @poltura/theme-sdk/inbox | The store's live chat: its state and actions, the complete widget and the parts it is built from. |
| slots | @poltura/theme-sdk/slots | App slots, app zones and host widget names. |
| ui | @poltura/theme-sdk/ui | Generic interface primitives, class merging and DOM hooks. |
| editor | @poltura/theme-sdk/editor | The customizer canvas: whether the page is being edited, and preview scenarios. |