Building sections for souk-theme ​

Welcome. This guide is for developers adding new sections to the souk-theme — the modern, visually-edited Storeino storefront.

What is souk-theme? ​

souk-theme is a Nuxt 3 storefront that renders any number of merchant pages (home, product, cart, blog, etc.) from a database-driven list of sections. A merchant uses the visual builder at admin.storeino.world/theme-builder/ to drag sections onto a page, edit their text/images/colors, and save. The storefront re-renders accordingly.

You will work mostly in one folder:

souk-theme/components/sections/<YourSection>/
  ├── index.vue       ← the Vue component
  └── manifest.json   ← describes its editable fields

A section is registered just by existing on disk — there is no central list to update. Drop the folder, restart dev, the builder picks it up.

What you will NOT need to know ​

You can build sections without learning these things:

• The postMessage bridge that lets the builder talk to the iframe
• How patches are sent from the builder UI back into the theme's Pinia store
• BunnyCDN, the deploy pipeline, or the theme-manager Express proxy
• The api-stores backend or the JWT auth flow

Those layers exist, and they work. Ask Abdel before touching them. For section work they are background details.

What you DO need ​

• Vue 3 (Composition API) — <script setup> style.
• TypeScript basics — every section is typed; the BannerConfig interface in Banner/index.vue is a representative example.
• Tailwind CSS — utility classes; we lean on it heavily.
• JSON — manifests are JSON, no DSL.
• Eye for design — sections are real layout work, not boilerplate.

How this guide is organized ​

1. Introduction (you are here)
2. Getting started — clone the repo, run dev, open the storefront
3. Anatomy of a section — every file, every field, what each one does
4. Writing the component — composables, props, styles, slots
5. Writing the manifest — schema fields, defaults, styleKeys
6. Testing in the builder — drag it in, edit, see it render live
7. Troubleshooting — "my section isn't showing up", the common failure modes
8. Deploying — the scripts that ship your section to merchants

Read them in order. Each builds on the last.

A note on the legacy themes ​

You may see another Themes section in the sidebar describing a different system — config.schema, config.current, config.settings, the in-admin Customizer. That covers older themes (marketmall, argan, bazar). Ignore it for souk-theme work. Souk uses a separate model: config.templates, config.tokens, config.global, and the visual builder. The two coexist; old merchants stay on their old themes, new merchants get souk.

A note on npx @storeino/themes-cli ​

You may also see this command referenced in older guides. It scaffolds a Nuxt project using the legacy theme model (the one in the previous paragraph) and is not what souk-theme is built on. It cannot scaffold a souk-style theme. For section work you only need to clone souk-theme directly — no CLI involved.

Ready? Open Getting started.