fcomursDocs

Theme Developer Guide

প্রথমবার? আগে theme-tutorial.md পড়ো: Node install থেকে publish পর্যন্ত ধাপে ধাপে, একটা পুরো উদাহরণ section সহ। এই guide হলো তার পরের পূর্ণ reference।

অবস্থা: সম্পূর্ণ (Phase 1–5) — theme folder, check, dev (যেকোনো store-এ Development theme), pull/push, registry-তে publish/rollback, store-এর Versions-এ Add / Customize / Preview / Publish / .zip / Update। এখন শুধু fcomurs team (first-party) theme বানায়।

সহজ ভাষায় — পুরো ব্যাপারটা এক পাতায়

Diagram
তুমি (VS Code)                          fcomurs registry              merchant-এর store: Online store
──────────────                          ────────────────              ──────────────────────────────
themes/aurora/                                                        ┌ Live (shopper দেখে) — উপরের card
  check  ─ ভুল খোঁজে                                                   └ Versions — এক table-এ সব:
  dev    ─ store-এ "Development" theme ──────────────────────────────►    Development · Draft theme ·
  publish ─────────────────────────────► aurora 1.0.0 ──Add theme──►     তোমার design-এর version · আগের live
  pull / push ◄──── store-এর theme ⇄ folder ─────────────────────────►    Customize · Preview · Publish · ⋯
তুমি চাওকী করবে
নতুন theme শুরুnode scripts/theme.js new aurora, themes/aurora/ VS Code-এ খোলো
ভুল আছে কিনাnode scripts/theme.js check aurora
Store-এ বসিয়ে কাজ করা (live না ছুঁয়ে)node scripts/theme.js login (dashboard-এ Allow), node scripts/theme.js dev aurora, যে preview link দেয় সেটা খোলো; প্রতিটা save-এ ~১ সেকেন্ডে reload। Store-এর Versions-এ "Development" row — shopper কিছুই দেখে না
Store-এর theme folder-এ আনা / ফেরত পাঠানোtheme.js pull "Starter", folder; বদলে theme.js push themes/starter --theme "Starter" (live theme-এ শুধু --live দিয়ে, জিজ্ঞেস করে)
সব store-কে দেওয়াnode scripts/theme.js login --console, publish aurora (designer-রা)
Merchant-এর store-এOnline store, Versions, Add theme, Customize (editor), Preview (শুধু নিজের browser), Publish
Theme .zipVersions-এ theme row-এর ⋯, Download (.zip); Add theme, Upload .zip — একই check, ভুলে file:line, কিছুই যোগ হয় না (Custom code access লাগে)
fcomurs নতুন version দিলেRow-এ "Update to 1.1.0 available", কী বদলাবে দেখায়, Make the updated copy — নতুন copy Versions-এ, merchant-এর নিজেরটা হুবহু থাকে; তাদের বদল (setting, মুছে ফেলা section, নিজের section, ক্রম) থেকে যায়
ভুল publish হলে ফেরাtheme.js rollback aurora 1.0.0, বা console, Templates, Coded themes, Make live
Store-এ আগের design-এ ফেরাLive coded theme-এর ⋯, Switch back to your own design

Live theme নিজে থেকে কখনো বদলায় না। Store-এর নিজের page (About, policy), landing page, product, order — theme কখনো ছোঁয় না।

পুরো theme নিজের VS Code-এ, এই repo-র themes/<name>/ folder-এ লেখা হয়। Merchant install করলে theme-এর একটা copy তার store-এ যায়, আর প্রতিটা section editor-এ বদলানো যায়।

১.শুরু

দুইভাবে চালানো যায়, command একই:

কেকীভাবেকোন server-এ
যেকোনো developer (fcomurs repo ছাড়া)npm package fcomurs-theme: npm create fcomurs-theme@latest <name>, তারপর theme folder-এ npx fcomurs-theme <command> (বা npm run dev/check)বাই default live fcomurs (api.fcomurs.com); login/dev/pull/push-এ --store <handle> লাগে
fcomurs repo-র ভেতরেnode scripts/theme.js <command>; theme থাকে themes/<name>-এবাই default নিজের computer-এর dev server

ধাপে ধাপে শুরু থেকে: theme-tutorial.md। নিচের উদাহরণ repo-র command-এ লেখা; package-এ node scripts/theme.js-এর জায়গায় npx fcomurs-theme, আর theme-এর নাম বাদ দিলে চলতি folder।

bash
node scripts/theme.js new aurora     # themes/aurora বানায়
node scripts/theme.js check aurora   # সব ভুল file:line:column সহ

new-এর theme সঙ্গে সঙ্গে check পাস করে। একটা পূর্ণ উদাহরণ দেখতে themes/starter।

Commandকী করেExit code
new <name>themes/<name>-এ ছোট একটা theme (home + product, একটা নিজের section)0, ভুল নাম বা folder আগে থেকে থাকলে 2
check <name|folder>§৫-এর সব যাচাই, সব ভুল একবারেerror থাকলে 1, শুধু warning হলে 0
check … --jsonএকই, JSON-এ (CI বা editor-এর জন্য)ঐ
login [--store h] [--no-browser]store admin-এ "Allow", ৮ ঘণ্টার theme dev token (§৮)0 / 2
dev <name|folder> [--store h] [--once]check, development store-এ push, প্রতিটা save-এ আবার push (§৮)--once: push হলে 0, error থাকলে 1

check-এর জন্য server বা database লাগে না — শুধু Node।

২.Folder

Diagram
themes/aurora/
├── theme.json                 নাম, version, themeApi, রং, templates, requires
├── templates/                 প্রতিটা page-এ কোন section কোন ক্রমে
│   ├── home.json
│   └── product.json …
├── sections/<name>/           theme-এর নিজের section
│   ├── section.html           Handlebars template
│   ├── style.css              শুধু এই section-এ লাগে
│   ├── script.js              export default function init(section, fc)
│   └── settings.json          merchant editor-এ যা বদলাতে পারে
├── blocks/<name>/             একই format (block.html, settings.json …)
├── layout/                    header/footer .html .css .js
├── assets/                    ছবি, svg, font
├── migrations/                update-এর নিয়ম (Phase 5)
├── site.css                   পুরো page-এর CSS (font, body …)
└── site.js

Section আর block-এর folder-এর নাম: ছোট হাতের অক্ষর, সংখ্যা আর - (hero-split)। Built-in section-এর নামে _ থাকে (product_grid), তাই দুটো কখনো গুলিয়ে যায় না।

৩.theme.json

JSON
{
  "name": "Aurora",
  "version": "1.0.0",
  "themeApi": 1,
  "description": "Big pictures, few words",
  "category": "Fashion",
  "author": "fcomurs",
  "cover": "assets/cover.jpg",
  "colors": { "buttonColor": "#111111", "primaryColor": "#111111", "navbarColor": "#ffffff", "backgroundColor": "#ffffff" },
  "templates": ["home", "product", "collection", "cart"],
  "requires": { "sections": ["product_main", "collection_main", "product_grid"] }
}
Keyবাধ্যতামূলকমানে
nameহ্যাঁ≤ ৬০ অক্ষর
versionহ্যাঁsemver 1.0.0; প্রতিটা publish-এ বাড়ে
themeApiহ্যাঁকোন format-এ লেখা; এখন শুধু 1
colorsনাশুধু এই চারটা key, hex রং
coverনাtheme library-র ছবি; file থাকতেই হবে
templatesনাtheme যে page-গুলো design করেছে; প্রতিটার templates/<name>.json থাকতে হবে। বাকি page install-এ merchant-এর আগেরটাই থাকে
requires.sectionsনাযে built-in section ছাড়া theme চলে না

Template-এর নাম: home, product, collection, collections, shop, featured, brand, blog, article, cart, wishlist, track, account।

৪.Template

JSON
{
  "sections": [
    { "id": "hero", "type": "hero-split", "settings": { "heading": "New season" } },
    { "id": "new", "type": "product_grid", "settings": { "sort": "newest", "count": 8 } },
    { "id": "promises", "type": "feature-list", "blocks": [
      { "type": "feature", "settings": { "title": "Your promise here" } }
    ] }
  ]
}
নিয়মকেন
প্রতিটা section-এর একটা স্থায়ী id (অক্ষর, সংখ্যা, -, _; এক template-এ একবার)Update-এ fcomurs merchant-এর বদল আর theme-এর বদল id ধরে মেলায় — id বদলালে ওটা "নতুন section"
type = theme-এর sections/<name> বা built-in section (product_grid, hero …)
settings-এ শুধু ঐ section-এর setting; _ দিয়ে শুরু key (Style tab: _paddingTop …) সবসময় চলে
Page template-এ ঐ page-এর main section থাকতেই হবে (product, product_main, cart, cart_main …)ওটাই product/cart আঁকে
কিছু built-in শুধু নির্দিষ্ট page-এ চলে (related_products শুধু product-এ)check বলে দেয়

Built-in section-গুলোর তালিকা আর setting: apps/storefront/sections/<type>/schema.json, বা storefront-এর /dev/sections gallery।

৫.Section

section.html — Handlebars

Handlebars
<div class="hero hero--image-{{settings.imageSide}}">
  <h1>{{settings.heading}}</h1>
  {{#if settings.buttonLabel}}<a class="hero__button" href="{{settings.buttonLink}}">{{settings.buttonLabel}}</a>{{/if}}
  <img src="{{asset "hero.svg"}}" alt="" width="800" height="800">
  <ul>{{#each blocks}}<li>{{settings.title}}</li>{{/each}}</ul>
</div>

Template যা পায়: settings (এই section-এর), blocks (প্রতিটার settings), store (name, logo, phone, email, address, currencySymbol)। Product/collection setting object হিসেবে আসে। যা ছাপা হয় সব auto-escape।

Helperকাজ
if unless each with lookupHandlebars-এর নিজের
eq ne gt lt and or notতুলনা: {{#if (eq settings.align "center")}}
default{{default settings.heading "Welcome"}}
moneyদাম store-এর currency-তে
linesলেখার প্রতিটা line আলাদা item: {{#each (lines settings.items)}}
embed encodevideo link, embed, URL encode
uidএই copy-র নিজের id: id="{{uid "slide"}}", slide-<section id>
assettheme-এর asset-এর ঠিকানা: {{asset "hero.jpg"}}

এর বাইরে কোনো helper নেই — check অজানা helper-এ error দেয় (কাছাকাছি নাম থাকলে "did you mean")।

style.css

শুধু এই section-এ লাগে — fcomurs প্রতিটা rule-এর আগে section-এর নিজের prefix বসায় (Phase 2)। তাই html, body, :root, * এখানে লিখবে না; ওগুলো site.css-এ। Asset: url("../assets/x.svg")।

script.js

JavaScript
export default function init(section, fc) {
  const button = section.querySelector('.hero__button');
  const onClick = () => {};
  button?.addEventListener('click', onClick);
  return () => button?.removeEventListener('click', onClick); // cleanup
}

Section-এর প্রতিটা copy-র জন্য একবার চলে; section = ঐ copy-র element। document.querySelector বা window.x = … না — ওগুলো অন্য section ছোঁয়। JS কখনো server-এ চলে না।

settings.json

JSON
{
  "settings": [
    { "key": "heading", "label": "Heading", "kind": "text", "default": "Made to last" },
    { "key": "imageSide", "label": "Image on the", "kind": "select", "default": "right",
      "options": [{ "value": "left", "label": "Left" }, { "value": "right", "label": "Right" }] }
  ],
  "blocks": [
    { "type": "feature", "label": "Feature", "fields": [{ "key": "title", "label": "Title", "kind": "text" }] }
  ],
  "max_blocks": 6
}

kind: text · textarea · richtext · image · url · select · number · range · checkbox · color · datetime · product · collection · collections · form।

নিয়ম
key অক্ষর দিয়ে শুরু, অক্ষর/সংখ্যা/_; একবারই
select-এ options লাগবে; default option-এর একটা হতে হবে
range/number: min ≤ max, default তার মধ্যে
checkbox-এর default true/false
label না থাকলে warning (merchant key দেখে)

layout/header.html আর layout/footer.html থাকলে theme নিজের header/footer আনে — store-এর header/footer-এর জায়গায় (preview-এ, live-এ, editor-এ)। না থাকলে store-এর নিজেরটাই থাকে। এগুলো Handlebars না — store-এর code header-এর মতো placeholder ভরে:

ফাইলPlaceholder
header.html{{logo}} {{store_name}} {{menu}} {{search}} {{cart_count}} {{phone}} {{email}}
footer.html{{logo}} {{store_name}} {{about}} {{categories}} {{quick_links}} {{info_links}} {{support_links}} {{extra_links}} {{social}} {{phone}} {{email}} {{address}} {{copyright}} {{year}}

header.css/footer.css পুরো page-এর CSS (scope নেই); header.js/footer.js section-এর মতোই export default function init(section, fc), section = header বা footer। অজানা placeholder-এ check সতর্ক করে। Editor-এ coded theme customize করার সময় header/footer বদলানো যায় না (theme-এর code, বা store-এর নিজের design-এ)।

Animation — script.js-এ GSAP আর Motion

Library চাইতে হয় settings.json-এ; store সেগুলো শুধু সেই page-এ load করে যেখানে কোনো section চেয়েছে, নিজের bundle থেকে (CDN না):

JSON
{ "settings": [], "uses": ["gsap", "scrolltrigger"] }
JavaScript
export default function init(section, fc) {
  if (fc.reducedMotion) return;
  fc.gsap.from(section.querySelectorAll('.card'), { y: 24, opacity: 0, stagger: 0.08, scrollTrigger: { trigger: section } });
}
usesfc-তে
gsapfc.gsap
scrolltriggerfc.ScrollTrigger (সাথে gsap-ও আসে)
motionfc.motion — animate, scroll, inView, stagger

Script এগুলো দিয়ে যা শুরু করে, section চলে গেলে সব নিজে থেকেই থামে (GSAP context; প্রতিটা Motion animation)। যে shopper motion বন্ধ রেখেছে তার জন্য fc.reducedMotion true — script এটা না দেখে animate করলে check warning দেয়। uses-এ না লিখে GSAP বা Motion ব্যবহার করলে error।

React section — section.tsx

section.html + settings.json + script.js-এর বদলে একটা section React component হতে পারে। এক theme-এ দুই ধরনই থাকতে পারে। fcomurs-theme new <name> --react এমন একটা section-সহ theme বানায়।

tsx
// sections/hero/section.tsx
import { defineSection, text, image, collection, block, Image, Money } from '@fcomurs/theme';
import AddButton from '../../components/AddButton'; // 'use client' — একটা island

export default defineSection({
  name: 'Hero',
  settings: {
    heading: text({ label: 'Heading', default: 'New season' }),
    picture: image({ label: 'Picture', phone: true }),
    collection: collection({ label: 'Collection' }),
  },
  blocks: { badge: block({ label: text() }, { label: 'Badge' }) },
  async data({ settings, store }) {
    return { products: await store.products({ collection: settings.collection?.slug, limit: 4 }) };
  },
  render: ({ settings, blocks, data }) => (
    <section className="hero">
      <h1>{settings.heading}</h1>
      <Image src={settings.picture} alt="" />
      {blocks.map((b) => <span key={b.id}>{b.settings.label}</span>)}
      {data.products.map((p) => <p key={p.id}>{p.title} <Money amount={p.price} /> <AddButton productId={p.id} /></p>)}
    </section>
  ),
});
অংশকীভাবে কাজ করে
settingsField builder: text textarea richtext url color datetime checkbox number range select image product collection collections। Editor-এর panel এগুলো থেকেই আসে — settings.json নেই। Type নিজে থেকে মেলে: settings.heading একটা string, settings.collection একটা Collection | null।
image({ phone: true })ঐচ্ছিক phone ছবি যোগ করে; value হয় { src, phone }। <Image src={…} /> ৬৩৯px পর্যন্ত চওড়া screen-এ phone দেখায়।
blocksblock({ fields }, { label }); maxBlocks দিয়ে সীমা (default ৫০)।
dataশুধু server-এ, render-এর আগে। store.products({ collection, sort, limit ≤ 24 }), store.product(slug), store.collection(slug) (১২টা product-সহ), store.collections() (product ছাড়া)। সর্বোচ্চ ২০টা call, ৫ সেকেন্ড।
renderশুধু server-এ, প্রতি page view-এ একবার: এর HTML যেমন আছে তেমন browser-এ যায়, আর কখনো আবার আঁকা হয় না।
'use client'যে file এটা দিয়ে শুরু, তার component-গুলো client component: section-এর সাথে server-এ আঁকা হয়, তারপর browser-এ জেগে ওঠে ("island")। শুধু এগুলোই JavaScript পাঠায়। Props plain data হতে হবে (function বাদ যায়); server-এ আঁকা children যেমন আছে তেমন থাকে। useState, effect, Motion, GSAP এখানে।
Importশুধু theme-এর নিজের file (sections/, components/, lib/, islands/) আর react, react-dom, motion, motion/react (framer-motion একই), gsap, gsap/ScrollTrigger, @fcomurs/theme। CSS import না — section.tsx-এর পাশে style.css আগের মতোই scoped; Tailwind-এর output site.css-এ।
Typenpm install @fcomurs/theme react motion আর @types/react (--react project-এ আগেই আছে) — তাহলে VS Code settings, data আর store-এর autocomplete দেয়।

Build: প্রতিটা dev push, push, upload আর publish-এ fcomurs নিজেই TSX compile করে। ভুল আসে file আর line-সহ (sections/hero/section.tsx:12: …) — terminal-এ, আর খোলা preview-এ একটা লাল panel-এ; ঠিক না করা পর্যন্ত preview শেষ ভালো save-টাই দেখায়।

নিরাপত্তা: theme-এর server code কখনো store-এর server-এ চলে না। চলে আলাদা একটা worker process-এ — environment variable নেই, file নেই, child process নেই — আর নিজের একটা ফাঁকা JavaScript context-এ (process, require, fetch, eval কিছুই নেই)। যে section throw করে, এক সেকেন্ডের বেশি চলে, বা বেশি memory খায়, সেটা page থেকে বাদ যায়; বাকিটা আঁকা হয়।

Motion-এর টিপ: client component server-এ যা আঁকে সেটা তার প্রথম frame — initial={{ opacity: 0 }} হলে browser জাগানো পর্যন্ত লুকানো থাকে। Page-এর একদম উপরের লেখার জন্য initial={false} বা ছোট animation দাও।

৬.check কী দেখে

Error (exit 1):

যাচাইউদাহরণ বার্তা
ভুল JSONtheme.json:4:3 Unexpected """ — a comma or "}" was expected (is a comma missing?)
Handlebars syntax, অজানা helper"mony" isn't a helper — did you mean "money"?
Asset নেই ({{asset}}, CSS url())assets/nope.png doesn't exist
অজানা section type"product_gird" is neither … — did you mean "product_grid"?
Duplicate section idid "a" is used twice in this template (first on line 4)
Built-in section ভুল page-এ"product_main" only works in the product template
Page-এর main section নেইThe product page needs its main section
requires.sections-এ অজানা section"mega_menu" isn't a built-in section of this fcomurs
themeApi, version, রংthemeApi 9 isn't one this fcomurs can run
ভুল settings schemaঅজানা kind, option নেই, default option-এ নেই, duplicate key
Template-এ অজানা setting বা ভুল select মান"intro" has no setting "headline" — did you mean "heading"?
ছবি > 2 MB

Warning (exit 0, কিন্তু ঠিক করো):

ধরনযাচাই
Isolationsection CSS-এ html/body/:root/*; script-এ window.x =, document.querySelector
Duplicate idহুবহু id="..." — {{uid}} ব্যবহার করো
Performanceছবি > 500 KB; section-এর CSS+JS > 30 KB; theme-এর মোট JS/CSS > 150 KB; <img>-এ loading="lazy" নেই (page-এর প্রথম section ছাড়া) বা width/height নেই
Mobile৬০০px-এর বেশি স্থির width
Accessibility<img>-এ alt নেই; <a>/<button>-এ লেখা বা aria-label নেই; <input>-এ label নেই; heading-এর ধাপ লাফ (h2, h4)

৭.Store-এ চালানো — login, dev, pull, push

bash
node scripts/theme.js login            # browser-এ store admin খোলে → Allow
node scripts/theme.js dev starter      # push, তারপর প্রতিটা save-এ আবার
Diagram
VS Code-এ save ──► theme.js dev ──► check (error? → push হয় না, store আগেরটাই দেখায়)
                                  └► PUT /api/theme-dev/theme ──► API: package বানায়
                                       (CSS scope, script → init, asset ঠিকানা) ──► DevTheme
store-এর খোলা page ◄── প্রতি সেকেন্ডে revision দেখে, বদলালে reload  (~১ সেকেন্ড)
নিয়মকীভাবে
যেকোনো store, live কখনো নাdev folder-কে তোমার Development theme বানায় (store-এর Versions-এ, প্রতি developer-এ একটা), প্রতিটা push সেটাই বদলায়; দেখা যায় শুধু preview link-এ (৮ ঘণ্টা)। Publish করা যায় না — Duplicate করে copy publish করো
Tokenlogin admin-এর "Allow" থেকে ৮ ঘণ্টার token — শুধু theme dev route, শুধু ঐ store, Custom code access থাকলে। রাখা হয় ~/.fcomurs/theme-credentials.json-এ (শুধু user পড়তে পারে), repo-তে কখনো না। CI-তে FCOMURS_THEME_TOKEN
এই computer ছাড়া অন্য server--api https://… দিলে --store <handle> লিখতেই হবে, আর token-এর store-এর সাথে মিলতে হবে
pull / pushpull --list store-এর theme-গুলো; `pull <নামid> [folder] (খালি folder-এ); push <folder> --theme <নামid> — folder-এর code আর page সেই theme-এ (live-এ শুধু --live`)

Theme section store-এ কীভাবে আঁকা হয় (apps/storefront/lib/renderer/):

ধাপকী হয়
PageresolvePage() — theme-এর template থেকে section-এর তালিকা; theme-এর section theme:<name>, built-in নিজের type-এ
SettingsmergeSettings() — settings.json-এর default ← theme-এর মান ← merchant-এর মান
Dataসব section-এর data একসাথে server-এ (product/collection setting, object)
HTMLHandlebars, server-এ; প্রতিটা copy একটা <div data-fc-s="<theme>-<section>">-এ, তার scoped CSS সহ
Scriptbrowser-এ, প্রতিটা copy-র জন্য init(section, fc); ফেরত দেওয়া cleanup section সরলে চলে
ভুলtemplate-এ ভুল বা কোনো section throw করলে store-এ শুধু ঐ section বাদ, বাকি page আঁকা হয়

CSS scope (API services/theme/cssScope.js): .x, [data-fc-s="…"] .x, :scope = section নিজে, html/body/:root, section, @keyframes আর @font-face-এর নামে section-এর prefix, url(../assets/x), theme-এর asset-এর ঠিকানা, @import বাদ।

৮.Publish আর rollback

শুধু fcomurs-এর designer (console-এ super admin, বা Team page-এ designer চিহ্ন দেওয়া কেউ)।

bash
node scripts/theme.js login --console        # console-এ Allow → ১ ঘণ্টার publish token
node scripts/theme.js publish aurora         # theme, version, server দেখায়, y চায়
node scripts/theme.js publish aurora --draft # তৈরি, কিন্তু live না
node scripts/theme.js rollback aurora 1.2.0  # কোন version live — শুধু এটুকু বদলায়
নিয়মমানে
Theme-এর নাম = folder-এর নামthemes/aurora, aurora; এটা কখনো বদলায় না
version প্রতিবার বাড়াতে হবেএকই version আবার, বা সবচেয়ে নতুনটার চেয়ে পুরোনো version, refuse (409)
Published version কখনো বদলায় নাভুল হলে নতুন version publish করো; database-ও কোনো update নেয় না
Rollback = শুধু "live" pointerকোনো version-এর file বদলায় না; আগে install করা store-ও বদলায় না
--yesজিজ্ঞেস করে না — শুধু CI-তে (FCOMURS_PUBLISH_TOKEN সহ)
ConsoleTemplates, Coded themes: প্রতিটা theme-এর version, কে কখন publish করেছে, "Make live"। প্রতিটা publish ও বদল Activity log-এ

Publish কীভাবে নিরাপদ (R2 আর database একসাথে transaction হয় না):

Diagram
CLI:    check ──► প্রতিটা file-এর sha256 ──► "Publish? (y/N)"
          └► POST uploads {manifest} ──► শুধু যা server-এ নেই তা PUT (hash দিয়ে)
Server: hash না মিললে refuse ──► finish:
          ৪ staging-এর প্রতিটা file আবার hash
          ৫ পুরো theme আবার যাচাই (CLI-র check-এ ভরসা না)
          ৬ asset → themes/<key>/<version>/, পড়ে আবার hash
          ৭ ThemeVersion লেখা         ← কেউ দেখে না
          ৮ Theme.currentVersion = এটা ← একটা update = "publish"
          ৯ staging মোছা

৮-এর আগে যেকোনো জায়গায় থামলে কিছুই publish হয় না। ৬-এ থামলে copy করা asset মুছে যায়; ৭-এর পরে থামলে version থাকে কিন্তু live হয় না (rollback দিয়ে live করা যায়)। অর্ধেক upload প্রতি ঘণ্টার job মুছে দেয় (একদিন পরে)।

Asset: R2 থাকলে R2_PUBLIC_URL/themes/<key>/<version>/<file>; না থাকলে API-র /api/theme-assets/<key>/<version>/<file> (THEME_FILES_DIR, default apps/api/theme-files/)। চিরদিনের cache — version-এর file কখনো বদলায় না।

৯.Code কোথায়

কীকোথায়
CLIscripts/theme.js (command-এর নাম আর default ঠিকানা: scripts/theme/defaults.js)
npm packagepackages/theme-cli (fcomurs-theme): build.mjs repo-র CLI আর তার check (apps/api/services/theme/*, built-in section-এর তালিকা, Handlebars, fflate) এক file-এ বাঁধে, defaults.js-এর জায়গায় src/defaults.js (live fcomurs, চলতি folder) বসায়। packages/create-fcomurs-theme (npm create fcomurs-theme) শুধু নাম জিজ্ঞেস করে new চালায়, project file-সহ (package.json, .gitignore, README — এগুলো theme-এর অংশ না, check/dev বাদ দেয়)
Format-এর তালিকা (template, helper, kind, সীমা)scripts/theme/format.js — server-side validation-ও এটাই ব্যবহার করবে
যাচাইscripts/theme/check.js (line ধরে JSON: scripts/theme/json.js)
newscripts/theme/scaffold.js
login, dev, pull, pushscripts/theme/devClient.js
Package (scope, init, asset)apps/api/services/theme/{package,cssScope,script}.js
Dev route, tokenapps/api/controllers/themeDevController.js, middleware/themeDevAuth.js (Development theme = StoreTheme role development)
Rendererapps/storefront/lib/renderer/ (resolve.ts, handlebars.ts, storeTheme.ts), components/sections/SectionGuard.tsx
Admin-এর "Allow" pageapps/dashboard/app/theme-cli/page.tsx (dev), apps/console/app/theme-cli/page.tsx (publish)
Publish, rollbackCLI scripts/theme/publishClient.js; API services/theme/{publish,files}.js, controllers/themeRegistryController.js, middleware/themePublishAuth.js, models/{Theme,ThemeVersion,ThemeUpload}.js
ConsoleTemplates, Coded themes (apps/console/app/(console)/templates/CodeThemes.tsx)
.zipAPI services/theme/archive.js (fflate; path, সংখ্যা, unpack-এর মাপ আগে যাচাই), storeThemeController download/upload; check এখন apps/api/services/theme/check.js-এ (CLI-ও সেটাই চালায়)
Store-এর theme libraryAPI models/StoreTheme.js, controllers/storeThemeController.js (/online-store/store-themes, /online-store/public/store-theme); dashboard components/online-store/CodedThemes.tsx, editor ?storeTheme=<id>&template=<page>; storefront lib/renderer/devTheme.ts fetchStoreTheme
TestAPI: test/theme/{check,package}.test.js, test/saas/themeDev{,Cli}.test.js, test/saas/themeRegistry.test.js, test/saas/themePublishCli.test.js, test/saas/storeThemes.test.js, test/saas/storeThemeZip.test.js, test/saas/storeThemeUpdate.test.js, test/theme/merge.test.js; storefront: test/renderer.test.mjs
React sectionAPI services/theme/tsx.js (esbuild: শুধু theme-এর file, অনুমোদিত import, 'use client', server-এ island marker আর browser-এর জন্য একটা fc-islands.js), schemaWorker.js + isolated.js (settings পড়া হয় locked-down process-এ); storefront lib/renderer/renderTsx.server.ts + tsxWorker.cjs (আঁকা; instrumentation.ts-এ register), islands.ts (island জাগানো), app/theme-render/route.ts (editor-এর preview); SDK packages/theme-sdk (@fcomurs/theme; apps/api/services/theme/sdk.js হুবহু copy — একটা test মিলিয়ে দেখে)
Animation (uses)storefront lib/animationKit.ts; uses আছে config/codeSectionSchema.js-এ
Test (React, animation)API test/theme/tsx.test.js, test/saas/themeDev.test.js (error panel); storefront test/renderTsx.test.mjs, test/animationKit.test.mjs
নমুনাthemes/starter; React-এর জন্য: fcomurs-theme new <name> --react

নতুন helper, setting kind বা template যোগ হলে format.js বদলাও, আর এই guide-ও।

npm package ছাড়া (release): format, check বা built-in section বদলালে package-ও নতুন করে ছাড়তে হয়, নইলে বাইরের developer-রা পুরোনো নিয়মে check করবে। packages/theme-cli/package.json-এর version বাড়াও, cd packages/theme-cli && pnpm install && npm publish (prepublishOnly build চালায়)। create-fcomurs-theme বদলালে সেটাও আলাদা করে publish করো। দুটোই npm-এ fcomurs-এর account থেকে publish হয়।