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 বানায়।
সহজ ভাষায় — পুরো ব্যাপারটা এক পাতায়
তুমি (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 .zip | Versions-এ 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।
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
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
{
"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
{
"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
<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 lookup | Handlebars-এর নিজের |
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 encode | video link, embed, URL encode |
uid | এই copy-র নিজের id: id="{{uid "slide"}}", slide-<section id> |
asset | theme-এর 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
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
{
"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 দেখে) |
Header আর footer — layout/
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 না):
{ "settings": [], "uses": ["gsap", "scrolltrigger"] }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 } }); }
uses | fc-তে |
|---|---|
gsap | fc.gsap |
scrolltrigger | fc.ScrollTrigger (সাথে gsap-ও আসে) |
motion | fc.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 বানায়।
// 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>
),
});| অংশ | কীভাবে কাজ করে |
|---|---|
settings | Field 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 দেখায়। |
blocks | block({ 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-এ। |
| Type | npm 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):
| যাচাই | উদাহরণ বার্তা |
|---|---|
| ভুল JSON | theme.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 id | id "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, কিন্তু ঠিক করো):
| ধরন | যাচাই |
|---|---|
| Isolation | section 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
node scripts/theme.js login # browser-এ store admin খোলে → Allow node scripts/theme.js dev starter # push, তারপর প্রতিটা save-এ আবার
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 করো | ||
| Token | login 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 / push | pull --list store-এর theme-গুলো; `pull <নাম | id> [folder] (খালি folder-এ); push <folder> --theme <নাম | id> — folder-এর code আর page সেই theme-এ (live-এ শুধু --live`) |
Theme section store-এ কীভাবে আঁকা হয় (apps/storefront/lib/renderer/):
| ধাপ | কী হয় |
|---|---|
| Page | resolvePage() — theme-এর template থেকে section-এর তালিকা; theme-এর section theme:<name>, built-in নিজের type-এ |
| Settings | mergeSettings() — settings.json-এর default ← theme-এর মান ← merchant-এর মান |
| Data | সব section-এর data একসাথে server-এ (product/collection setting, object) |
| HTML | Handlebars, server-এ; প্রতিটা copy একটা <div data-fc-s="<theme>-<section>">-এ, তার scoped CSS সহ |
| Script | browser-এ, প্রতিটা 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 চিহ্ন দেওয়া কেউ)।
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 সহ) |
| Console | Templates, Coded themes: প্রতিটা theme-এর version, কে কখন publish করেছে, "Make live"। প্রতিটা publish ও বদল Activity log-এ |
Publish কীভাবে নিরাপদ (R2 আর database একসাথে transaction হয় না):
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 কোথায়
| কী | কোথায় |
|---|---|
| CLI | scripts/theme.js (command-এর নাম আর default ঠিকানা: scripts/theme/defaults.js) |
| npm package | packages/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) |
new | scripts/theme/scaffold.js |
login, dev, pull, push | scripts/theme/devClient.js |
| Package (scope, init, asset) | apps/api/services/theme/{package,cssScope,script}.js |
| Dev route, token | apps/api/controllers/themeDevController.js, middleware/themeDevAuth.js (Development theme = StoreTheme role development) |
| Renderer | apps/storefront/lib/renderer/ (resolve.ts, handlebars.ts, storeTheme.ts), components/sections/SectionGuard.tsx |
| Admin-এর "Allow" page | apps/dashboard/app/theme-cli/page.tsx (dev), apps/console/app/theme-cli/page.tsx (publish) |
| Publish, rollback | CLI scripts/theme/publishClient.js; API services/theme/{publish,files}.js, controllers/themeRegistryController.js, middleware/themePublishAuth.js, models/{Theme,ThemeVersion,ThemeUpload}.js |
| Console | Templates, Coded themes (apps/console/app/(console)/templates/CodeThemes.tsx) |
| .zip | API services/theme/archive.js (fflate; path, সংখ্যা, unpack-এর মাপ আগে যাচাই), storeThemeController download/upload; check এখন apps/api/services/theme/check.js-এ (CLI-ও সেটাই চালায়) |
| Store-এর theme library | API 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 |
| Test | API: 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 section | API 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 হয়।
