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.
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:
| Thing | It says | Example |
|---|---|---|
Template (templates/*.json) | Which sections a page has, in what order | home 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 it | HTML + 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.
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
| Thing | Why | Install on Windows | Check it worked |
|---|---|---|---|
| Node.js 20 or newer (22 is best) | Runs the theme CLI; npm comes with it | Download the LTS from nodejs.org, or winget install OpenJS.NodeJS.LTS | node -v, v22…, and npm -v |
| VS Code (or any editor) | Writing the files | winget install Microsoft.VisualStudioCode | code --version |
| Chrome or any browser | Pressing Allow, seeing the preview | — | — |
| Git (optional) | Keeping your work | winget install Git.Git | git --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:
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.
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:
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
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
npm run check
✓ .: no problems
check needs no server. When something's wrong it shows file, line and column, like a compiler:
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 warningsWith 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
- Sign in to app.fcomurs.com in your browser.
- Open the store you'll work on (go into it from the Stores page).
- In the terminal, run:
npx fcomurs-theme login --store rafi-fashion
- The browser opens a page called Theme development by itself. If it doesn't, copy the link printed in the terminal into the browser.
- Press Allow. The page says "Done" and the terminal shows:
✓ Signed in: dev can push to rafi-fashion for 8 hours.
| Question | Answer |
|---|---|
| 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
npm run dev -- --store rafi-fashion
(npm hands everything after -- to the CLI. npx fcomurs-theme dev --store rafi-fashion does the same.)
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:
{ "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 open | Saves are pushed only while dev runs. Ctrl+C stops it |
| With errors nothing is pushed | The terminal shows the error, and the store keeps the last good version. Fix it, save, and it's pushed again |
| Shoppers see nothing | It's your Development theme, seen only through the preview link (8 hours) |
| In the store's admin | Online 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
{
"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:
| Field | Meaning |
|---|---|
key | The name you use in the template: {{settings.heading}} |
label | The name the merchant sees in the editor |
kind | The 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 |
default | Used when the merchant gives nothing |
blocks | Small 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
<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):
| Write | Meaning |
|---|---|
{{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
.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)
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); }
| Rule | Why |
|---|---|
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 end | When 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
{
"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 } }
]
}| Field | Meaning |
|---|---|
id | This 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 |
type | The folder name in sections/ (offer-banner), or a built-in section (product_grid) |
settings | Starting values; the merchant changes them later in the editor |
blocks | Which 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:
| Section | Does | On which page |
|---|---|---|
product_main | Product pictures, price, variants, Add to cart | product only (required there) |
related_products | Similar products | product only |
collection_main | All of a collection's products, with filters | collection only (required) |
cart_main | The cart | cart only (required) |
product_grid | A row of products (newest, best selling…) | any page |
hero, rich_text, faq … | General sections | any 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:
- Make
templates/collection.json:
{
"sections": [
{ "id": "main", "type": "collection_main" }
]
}- Add its name to
templatesintheme.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:
- app.fcomurs.com, Online store, Versions.
- On the Development row, ⋯, Duplicate. This makes a lasting copy called "Copy of …" (rename it with ⋯, Rename if you like).
- Press Customize on the copy. In the editor, change text, pictures and badges the way a merchant would, and check it all looks right.
- Look at it on a phone and a computer with Preview.
- 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:
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:
| Versions | A new version each time (version in theme.json: 1.0.0, then 1.0.1…). A published version never changes |
| Stores that installed it earlier | They don't change by themselves. Versions shows "Update available", and the merchant chooses when to update |
| The merchant's changes | Their 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:
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 says | What it means and the fix |
|---|---|
'fcomurs-theme' is not recognized, or npm run dev doesn't work | npm install didn't happen in the theme folder, or you're in another folder (step 2) |
'node' is not recognized | Node 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 Y | Another store was open in the admin. Open the right store and run login --store Y again |
The admin had X open, not Y | Same 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 access | Ask the store's owner to give you Custom code access in Settings, Staff |
1 error — not pushed | Look at the error's file:line in the terminal, fix it, save |
| Text is blank in the preview | A 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 preview | Check 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 twice | Two 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).
| Task | Command |
|---|---|
| New theme | npm create fcomurs-theme@latest <name> (or npx fcomurs-theme new <name>); with a React section: add -- --react |
| Look for mistakes | npm run check |
| Log in to a store (8 hours) | npx fcomurs-theme login --store <handle> |
| See it running in the store | npm run dev -- --store <handle> |
| The store's themes | npx fcomurs-theme pull --list --store <handle> |
| A store's theme into a folder | npx fcomurs-theme pull "<theme name>" <folder> --store <handle> |
| This folder into one of the store's themes | npx fcomurs-theme push --theme "<theme name>" --store <handle> |
| Go back to an earlier version | npx 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).
