fcomursDocs

Your first theme — from install to publish, step by step

This guide starts from nothing: what to install, how to make your first theme, how to see it running in a store, how to write your own section, and finally how to publish it in your store. Every step has one command and a way to tell that it worked.

Every rule in full (each setting, each check) is in the Theme Developer Guide. It's much easier to read after this one.

Diagram
Step 1  Install          Node.js (and VS Code)
Step 2  First theme      npm create fcomurs-theme → npm install → check
Step 3  Log in           npx fcomurs-theme login → Allow in the browser
Step 4  Dev              npm run dev → preview link → every save shows up
Step 5  Your section     settings.json + section.html + style.css
Step 6  Built-ins        product grid, product page, cart
Step 7  Into a store     Versions → Duplicate → Customize → Publish
Step 8  To every store   through the fcomurs team

You don't need any fcomurs source code. Everything runs through one npm package: fcomurs-theme.

First: what a theme actually is

A theme is a folder. It holds two kinds of things:

ThingIt saysExample
Template (templates/*.json)Which sections a page has, in what orderhome page = a banner, then a row of products, then some text
Section (sections/<name>/)What one section looks like, and what the merchant can change in itHTML + CSS + which text/pictures can be changed

Products, cart, checkout, orders — the store's real work — fcomurs does by itself. You only write the look.

Diagram
Your computer                          An fcomurs store
─────────────                          ────────────────
mytheme/  ── npm run dev ──►           a "Development" theme (only on your preview link)
  save in VS Code                        ↑ changes ~1 second after every save
                                         Shoppers see nothing

Step 1 — What to install

ThingWhyInstall on WindowsCheck it worked
Node.js 20 or newer (22 is best)Runs the theme CLI; npm comes with itDownload the LTS from nodejs.org, or winget install OpenJS.NodeJS.LTSnode -v, v22…, and npm -v
VS Code (or any editor)Writing the fileswinget install Microsoft.VisualStudioCodecode --version
Chrome or any browserPressing Allow, seeing the preview——
Git (optional)Keeping your workwinget install Git.Gitgit --version

Without winget, download each from its own website. After installing, close the terminal and open a new one, or the new commands won't be found.

You also need a store. One on app.fcomurs.com where you're the owner, or where you've been given Custom code access. It's best to open a separate test store for this. Theme dev never changes a live store, but working away from the real shop is safer.

Note the store's handle — the address you chose when you made it. If the store is at rafi-fashion.myfcomurs.com, the handle is rafi-fashion. In every command below, put your own handle where it says rafi-fashion.

Step 2 — Make your first theme

Open a terminal in the folder where you'll keep your work (e.g. D:\themes) and run:

powershell
npm create fcomurs-theme@latest mytheme

Used to React/Next.js? npm create fcomurs-theme@latest mytheme -- --react makes the first section a React component (section.tsx, with a 'use client' island that animates with Motion). The rules: "React sections" in theme-developer-guide.en.md. The rest of this tutorial uses HTML sections.

Diagram
Made mytheme (12 files). Next:
  cd mytheme
  npm install
  npx fcomurs-theme login --store <your store>
  npm run dev -- --store <your store>

Without a name it asks for one. Names use only lower-case letters, digits and - (My Shop becomes my-shop). If a folder with that name already exists, it isn't overwritten — you get an error.

Then:

powershell
cd mytheme
npm install
code .

npm install brings the theme CLI (fcomurs-theme) into this project. code . opens the folder in VS Code. Use Terminal, New Terminal there and the terminal opens in this folder. From now on, run every command from here.

What's in the folder

Diagram
mytheme/
├── theme.json                 the theme's name, version, colours, which pages it designs
├── templates/
│   ├── home.json              home page: intro section, then a row of new products
│   └── product.json           product page: the product, then related products
├── sections/
│   └── intro/                 your first section of your own
│       ├── settings.json      what the merchant can change in the editor
│       ├── section.html       the section's HTML (Handlebars)
│       ├── style.css          CSS for this section only
│       └── script.js          JavaScript for this section only (optional)
├── assets/                    images, svg, fonts
├── site.css                   CSS for the whole page (fonts, body)
├── package.json               npm scripts: login, dev, check (not part of the theme)
├── README.md                  (not part of the theme)
└── .gitignore                 (not part of the theme)

package.json, README.md, node_modules/, dist/ and files starting with . aren't part of the theme. The CLI never sends them to the store, and check doesn't look at them.

Look for mistakes

powershell
npm run check
Diagram
✓ .: no problems

check needs no server. When something's wrong it shows file, line and column, like a compiler:

Diagram
error   templates/home.json:13:15  "product_gird" is neither a built-in section nor in sections/ — did you mean "product_grid"?

1 error, 0 warnings

With an error the theme won't go to a store. With a warning it will, but fix it anyway (an image without alt, an image that's too big…).

Step 3 — Log in: let this computer into the store

  1. Sign in to app.fcomurs.com in your browser.
  2. Open the store you'll work on (go into it from the Stores page).
  3. In the terminal, run:
powershell
npx fcomurs-theme login --store rafi-fashion
  1. The browser opens a page called Theme development by itself. If it doesn't, copy the link printed in the terminal into the browser.
  2. Press Allow. The page says "Done" and the terminal shows:
Diagram
✓ Signed in: dev can push to rafi-fashion for 8 hours.
QuestionAnswer
How long does it last?8 hours. After that, run login again
Where's the token kept?In your own user folder, ~/.fcomurs/theme-credentials.json. Not in the theme folder, so it can't end up on GitHub by mistake
What can the token do?Work on that store's themes only. It can't touch orders, products or settings
What if I stop the login command before pressing Allow?The page says "Couldn't reach the theme CLI". Run the command again
Why --store?So a push never goes to the wrong store. The token is for whichever store is open in the browser, and --store checks it's the one you meant

Step 4 — Dev: see it running in the store

powershell
npm run dev -- --store rafi-fashion

(npm hands everything after -- to the CLI. npx fcomurs-theme dev --store rafi-fashion does the same.)

Diagram
Store: rafi-fashion — your Development theme there; shoppers keep seeing the live store.
Pushed (1) in 640 ms
Preview (this browser only, reloads on every save):
  https://rafi-fashion.myfcomurs.com/preview/version?token=…
Watching for changes — Ctrl+C to stop.

Open the Preview link in your browser. Your theme shows with that store's real products.

Now change something. Open templates/home.json and change the heading:

JSON
{ "id": "intro", "type": "intro", "settings": { "heading": "My first theme", "text": "Change this text in the editor." } },

Save (Ctrl+S). A new Pushed (2) appears in the terminal, and in about a second the browser page reloads by itself with the new text.

Remember
Keep the terminal openSaves are pushed only while dev runs. Ctrl+C stops it
With errors nothing is pushedThe terminal shows the error, and the store keeps the last good version. Fix it, save, and it's pushed again
Shoppers see nothingIt's your Development theme, seen only through the preview link (8 hours)
In the store's adminOnline store, Versions shows a "Development" row. Each developer has their own

Step 5 — Write your own section

Now let's make a new section: an offer banner. It has a heading, text, a picture, a button, a background colour, and a few small "badges" (like "Free delivery") that the merchant can add or remove.

Section folder names use lower-case letters and -. fcomurs's own built-in sections have _ in their names (product_grid), so the two never get mixed up.

5.1 sections/offer-banner/settings.json — what the merchant can change

JSON
{
  "settings": [
    { "key": "heading", "label": "Heading", "kind": "text", "default": "Eid sale — up to 30% off" },
    { "key": "text", "label": "Text", "kind": "textarea" },
    { "key": "image", "label": "Image", "kind": "image" },
    { "key": "buttonLabel", "label": "Button label", "kind": "text", "default": "Shop the sale" },
    { "key": "buttonLink", "label": "Button link", "kind": "url", "default": "/shop" },
    { "key": "background", "label": "Background colour", "kind": "color", "default": "#fff4e5" }
  ],
  "blocks": [
    { "type": "badge", "label": "Badge", "fields": [{ "key": "text", "label": "Text", "kind": "text" }] }
  ],
  "max_blocks": 4
}

Whatever you write here, the merchant gets exactly those fields on the right side of the editor:

FieldMeaning
keyThe name you use in the template: {{settings.heading}}
labelThe name the merchant sees in the editor
kindThe type of field: text, textarea (longer text), image (upload), url (link), color, select (pick from a list), number/range, checkbox (yes/no), product/collection (pick from the store). Full list: guide §5
defaultUsed when the merchant gives nothing
blocksSmall parts the merchant can add more than once; max_blocks is the most allowed

5.2 sections/offer-banner/section.html — what it looks like

Handlebars
<div class="offer" style="background: {{settings.background}}">
  <div class="offer__text">
    <h2>{{settings.heading}}</h2>
    {{#if settings.text}}<p>{{settings.text}}</p>{{/if}}
    {{#if blocks}}
      <ul class="offer__badges">
        {{#each blocks}}<li>{{settings.text}}</li>{{/each}}
      </ul>
    {{/if}}
    {{#if settings.buttonLabel}}<a class="offer__button" href="{{settings.buttonLink}}">{{settings.buttonLabel}}</a>{{/if}}
  </div>
  {{#if settings.image}}
    <img class="offer__image" src="{{settings.image}}" alt="{{settings.heading}}" width="600" height="600" loading="lazy">
  {{/if}}
</div>

It's ordinary HTML; values go inside {{ }} (this is called Handlebars):

WriteMeaning
{{settings.heading}}The heading the merchant gave. HTML inside it is escaped by itself, so it's safe
{{#if settings.text}} … {{/if}}Show this only when there is text
{{#each blocks}} … {{/each}}Once for every badge; inside, {{settings.text}} is that badge's text
{{store.name}}, {{store.phone}}The store's name, phone, email, address
{{money 1200}}A price in the store's currency
{{asset "hero.jpg"}}The address of an image in assets/

Always give <img> an alt, width and height, and loading="lazy" unless it's in the page's first section. Otherwise check warns.

5.3 sections/offer-banner/style.css — CSS for this section only

CSS
.offer { display: grid; gap: 24px; align-items: center; padding: 48px 16px; border-radius: 8px; }
@media (min-width: 768px) { .offer { grid-template-columns: 1fr 1fr; padding: 64px 48px; } }
.offer h2 { font-size: 2rem; margin: 0 0 8px; }
.offer__badges { display: flex; flex-wrap: wrap; gap: 8px; list-style: none; padding: 0; margin: 16px 0; }
.offer__badges li { padding: 4px 10px; border: 1px solid currentColor; border-radius: 4px; font-size: 0.875rem; }
.offer__button { display: inline-block; padding: 12px 20px; background: var(--btn-color, #111); color: #fff; text-decoration: none; }
.offer__image { width: 100%; height: auto; }

fcomurs puts this section's own prefix before every rule, so .offer h2 never reaches an h2 in another section. Don't write html, body, :root or * here; CSS for the whole page goes in site.css.

Mobile first: as above, write for phones first, then change things for bigger screens inside @media (min-width: 768px).

5.4 sections/offer-banner/script.js — JavaScript, if you need it (optional)

JavaScript
export default function init(section, fc) {
  const button = section.querySelector('.offer__button');
  const onClick = () => console.log('offer clicked');
  button?.addEventListener('click', onClick);
  return () => button?.removeEventListener('click', onClick);
}
RuleWhy
Use section.querySelector(...), not document.querySelector(...)The same section can be on a page twice; section is just this copy
return a cleanup function at the endWhen the section is removed in the editor, its event listeners go too
Don't write window.x = …It collides with other sections

JavaScript runs only in the browser, not in the editor's preview. Most sections don't need it at all.

5.5 Put it on a page — templates/home.json

JSON
{
  "sections": [
    { "id": "intro", "type": "intro", "settings": { "heading": "My first theme" } },
    {
      "id": "eid-offer",
      "type": "offer-banner",
      "settings": { "heading": "Eid sale — up to 30% off", "text": "Only this week." },
      "blocks": [
        { "type": "badge", "settings": { "text": "Free delivery" } },
        { "type": "badge", "settings": { "text": "Cash on delivery" } }
      ]
    },
    { "id": "new", "type": "product_grid", "settings": { "heading": "New arrivals", "sort": "newest", "count": 8 } }
  ]
}
FieldMeaning
idThis section's permanent name on this page. Don't change it later. When a new version comes, fcomurs keeps the merchant's changes by matching ids
typeThe folder name in sections/ (offer-banner), or a built-in section (product_grid)
settingsStarting values; the merchant changes them later in the editor
blocksWhich badges are there to begin with

Save. With dev running, the offer banner appears in the preview in about a second. If it doesn't, look at the terminal for an error.

Step 6 — fcomurs's built-in sections

You don't write products, collections or the cart yourself. Put fcomurs's built-in sections straight into a template:

SectionDoesOn which page
product_mainProduct pictures, price, variants, Add to cartproduct only (required there)
related_productsSimilar productsproduct only
collection_mainAll of a collection's products, with filterscollection only (required)
cart_mainThe cartcart only (required)
product_gridA row of products (newest, best selling…)any page
hero, rich_text, faq …General sectionsany page

For each built-in section's settings, open apps/storefront/sections/<type>/schema.json. Put one on the wrong page or misspell its name and check says so, with "did you mean".

To add a page:

  1. Make templates/collection.json:
JSON
{
  "sections": [
    { "id": "main", "type": "collection_main" }
  ]
}
  1. Add its name to templates in theme.json: "templates": ["home", "product", "collection"].

Pages the theme doesn't have keep the merchant's existing design. The pages there can be: home, product, collection, collections, shop, featured, brand, blog, article, cart, wishlist, track, account.

Your own header/footer: with layout/header.html and layout/footer.html, the theme brings its own header and footer. Write placeholders like {{logo}}, {{menu}}, {{cart_count}} in them. The full list and an example: guide §5 Header and footer.

Colours: colors in theme.json are the store's button, primary, navbar and background colours. The merchant can change them later in Settings.

Step 7 — Put the theme in a store

A Development theme can't be published directly, because it changes with every save. Make a lasting copy first:

  1. app.fcomurs.com, Online store, Versions.
  2. On the Development row, ⋯, Duplicate. This makes a lasting copy called "Copy of …" (rename it with ⋯, Rename if you like).
  3. Press Customize on the copy. In the editor, change text, pictures and badges the way a merchant would, and check it all looks right.
  4. Look at it on a phone and a computer with Preview.
  5. Press Publish. Shoppers now see this one.

If something's wrong, press Publish on the previous theme's row in Versions to bring the old design back. If the store had its own design before, use ⋯, Switch back to your own design on the live theme.

Changing it later: change the folder, then send it straight to that copy:

powershell
npx fcomurs-theme pull --list --store rafi-fashion
npx fcomurs-theme push --theme "Copy of Mytheme" --store rafi-fashion

The first command lists every theme in the store, with its name and id. push goes to the live theme only with --live, and even then it asks first.

A store's theme into a folder: npx fcomurs-theme pull "Starter" starter-copy --store rafi-fashion (the folder must be empty).

With a .zip: in Versions, a theme row's ⋯, Download (.zip), and Add theme, Upload .zip. Uploading runs the same check.

Step 8 — Want it in every store?

Step 7 is all you need for your own store. To get the theme into every fcomurs merchant's Add theme list, get in touch with the fcomurs team. The team reviews the theme and publishes it themselves, so this npm package has no publish command.

What happens after publishing:

VersionsA new version each time (version in theme.json: 1.0.0, then 1.0.1…). A published version never changes
Stores that installed it earlierThey don't change by themselves. Versions shows "Update available", and the merchant chooses when to update
The merchant's changesTheir own text, pictures and section order stay through an update

Keep your work (Git)

The theme folder is your own project. Keep it with Git, on your own GitHub if you like:

powershell
git init
git add .
git commit -m "mytheme: offer banner section"

The .gitignore already leaves out node_modules/ and dist/.

When something goes wrong

It saysWhat it means and the fix
'fcomurs-theme' is not recognized, or npm run dev doesn't worknpm install didn't happen in the theme folder, or you're in another folder (step 2)
'node' is not recognizedNode isn't installed, or the terminal wasn't reopened after installing
Not signed in (or the 8 hours are up)Run npx fcomurs-theme login --store <handle> again
api.fcomurs.com isn't this computer: say which store with --store <handle>You forgot --store
Signed in to X, not YAnother store was open in the admin. Open the right store and run login --store Y again
The admin had X open, not YSame reason: the token is for whichever store is open in the browser
The Allow page says "Sign in to the store admin"You're not signed in to app.fcomurs.com in that browser
The Allow page says "Couldn't reach the theme CLI"login stopped in the terminal (it stops by itself after 5 minutes). Run it again
You no longer have Custom code accessAsk the store's owner to give you Custom code access in Settings, Staff
1 error — not pushedLook at the error's file:line in the terminal, fix it, save
Text is blank in the previewA setting's name is misspelled in the template (e.g. settings.heding). Handlebars quietly shows a wrong name as blank, so compare it with the key in settings.json
Saving doesn't change the previewCheck dev is still running (Watching for changes in the terminal). Preview links expire after 8 hours — run dev again for a new one
"x" is neither a built-in section nor in sections/The type is misspelled, or the folder isn't in sections/
id "a" is used twiceTwo sections in one template share an id

Every command in one place

Run them from the theme's folder. For a theme in another folder, put the folder after the command (npx fcomurs-theme check mytheme).

TaskCommand
New themenpm create fcomurs-theme@latest <name> (or npx fcomurs-theme new <name>); with a React section: add -- --react
Look for mistakesnpm run check
Log in to a store (8 hours)npx fcomurs-theme login --store <handle>
See it running in the storenpm run dev -- --store <handle>
The store's themesnpx fcomurs-theme pull --list --store <handle>
A store's theme into a foldernpx fcomurs-theme pull "<theme name>" <folder> --store <handle>
This folder into one of the store's themesnpx fcomurs-theme push --theme "<theme name>" --store <handle>
Go back to an earlier versionnpx fcomurs-theme rollback <name> <version>

Another server (staging, say): set FCOMURS_API_URL and FCOMURS_ADMIN_URL. By default the CLI uses live fcomurs (api.fcomurs.com, app.fcomurs.com).

For fcomurs's own developers: inside the fcomurs repo the same CLI runs as node scripts/theme.js, against the dev servers on your computer (developer-guide.en.md).

What to read next: the Theme Developer Guide (every rule, every check, the full list of helpers).