Theme Development

Build a fully custom storefront theme for your Eekaam store using Liquid — the same template language used by Shopify. If you've built Shopify themes before, most of your knowledge transfers directly.

Install the Eekaam CLI Download the CLI and authenticate:

eekaam login

This opens a browser for OAuth. Credentials are saved to ~/.eekaam/config.toml.

Create a dev store eekaam store create --name "My Test Store"

This outputs a store ID (e.g. abc123def) you'll use in your theme config.

Scaffold a new theme eekaam theme init my-theme cd my-theme

This creates the full starter directory with a working layout, all core templates, settings schema, and an eekaam.toml config file.

Configure your store Edit eekaam.toml and set your store ID:

[environments.development] store = "abc123def"

Start the dev server eekaam theme dev

This uploads all local files, watches for changes, starts a proxy at http://127.0.0.1:9292, and injects live-reload so the browser refreshes on every save.

Validate your theme eekaam theme check

Checks required files, JSON validity, Liquid tag balance, external CDN usage, and size limits.

Package for submission eekaam theme package

Produces a ZIP file (e.g. my-theme-1.0.0.zip) ready to upload to the marketplace.

A theme is a folder of Liquid, JSON, CSS, JS, and image files organized into these subdirectories:

layout/ Contains theme.liquid — the required outer HTML wrapper rendered on every page. It must output {{ content_for_header }} in the head element and {{ content_for_layout }} in the body.

templates/ One file per page type. index.liquid (homepage) is required. Others: product, collection, cart, search, page, blog, article, 404, checkout, account, account-login, account-register, order-confirmation, track-order.

Templates can be Liquid files (full control) or JSON files (declarative section layout for the theme editor). JSON templates are preferred because merchants can drag-and-drop sections.

sections/ Reusable blocks of content with merchant-configurable settings. Each section file contains Liquid markup plus a {% schema %} block that defines settings editable in the theme editor. Recommended: sections/header.liquid and sections/footer.liquid.

snippets/ Partial templates included via {% render 'snippet-name' %}. Variables are not inherited from the parent scope — you must pass them explicitly. Example: {% render 'product-card', product: product %}

assets/ CSS, JS, images, and fonts. Reference them with {{ 'file.css' | asset_url | stylesheet_tag }} and {{ 'file.js' | asset_url | script_tag }}. Single images must be under 2 MB. Total theme must be under 10 MB.

config/ - settings_schema.json (required): defines global theme settings visible in the theme editor - settings_data.json: saved merchant values (auto-generated, don't edit manually)

locales/ Translation strings. locales/en.json is recommended. Use {{ 'key.path' | t }} in templates.

theme.json Theme manifest with name, version, author, description, and preview_image. Required for marketplace submission.

Sections are the building blocks of Eekaam themes. Merchants can configure them in the theme editor without touching code.

Basic section structure A section file has two parts: Liquid markup at the top, and a {% schema %} block at the bottom. The schema defines what settings appear in the theme editor.

Access settings in your markup with {{ section.SETTING_ID }}.

Schema setting types - text — single-line text input - textarea — multi-line text - richtext — rich text editor (outputs HTML) - image — image picker (value is a CDN URL) - url — URL input - color — color picker (hex string) - number — number input - range — slider (requires min, max, step, unit) - select — dropdown (requires options array) - checkbox — boolean toggle - collection — collection picker (value is collection handle) - product — product picker (value is product handle) - header — visual separator (no ID needed) - paragraph — read-only info text

Blocks Blocks let merchants add, remove, and reorder sub-elements within a section. Define allowed block types in the schema with a "blocks" array. Iterate them with {% for block in section.blocks %}. Access settings with block.settings.SETTING_ID, the type with block.type, and the unique ID with block.id. Use "max_blocks" in the schema to limit how many a merchant can add.

Rendering sections From a Liquid template: {% section 'hero' %} From a JSON template: sections are rendered automatically in the order defined by the "order" array.

Scoping section CSS Use section.id to scope styles: data-section-id="{{ section.id }}" on the wrapper div. Use {% style %} tags inside sections for dynamic styles that reference settings values.

Presets Add a "presets" array in the schema to make a section appear in the theme editor's "Add section" library with pre-filled default settings.

These global objects are available in every Liquid template.

shop {{ shop.name }}, {{ shop.domain }}, {{ shop.email }}, {{ shop.currency }}, {{ shop.locale }}, {{ shop.description }}, {{ shop.logo }}

Access navigation menus: {% for item in linklists['main-menu'].links %}

product (product templates only) {{ product.title }}, {{ product.slug }}, {{ product.description }}, {{ product.featured_image }}, {{ product.price }}, {{ product.compare_at_price }}, {{ product.available }}, {{ product.tags }}, {{ product.rating }}, {{ product.review_count }}

Variants: {% for variant in product.variants %} — each variant has id, title, price, sku, available, quantity, option1_value, image_url

Options (for variant pickers): {% for option in product.options %} — each has name, position, values

collection (collection templates) {{ collection.title }}, {{ collection.slug }}, {{ collection.description }}, {{ collection.image }} Products: {% for product in collection.products %}

cart (available on all pages) {{ cart.item_count }}, {{ cart.total_price | money }} Line items: {% for item in cart.items %} — each has title, quantity, price, line_price, image, url

customer (account pages, nil when not logged in) {{ customer.first_name }}, {{ customer.email }}, {{ customer.last_name }} Orders: {% for order in customer.orders %}

request {{ request.path }}, {{ request.page_type }}, {{ request.host }}, {{ request.locale.iso_code }}

template {{ template.name }} (e.g. "product"), {{ template.suffix }} Use for conditional asset loading: {% if template.name == 'product' %}

routes {{ routes.root_url }}, {{ routes.cart_url }}, {{ routes.cart_add_url }}, {{ routes.account_login_url }}, {{ routes.search_url }}

paginate (inside {% paginate %} blocks) {{ paginate.current_page }}, {{ paginate.pages }}, {{ paginate.items }} Parts: {% for part in paginate.parts %} — each has url, title, is_link

localization {{ localization.market.name }}, {{ localization.market.currency.iso_code }}, {{ localization.country.iso_code }}, {{ localization.country.name }} Markets list: {% for market in localization.available_markets %}

Money filters {{ product.price | money }} — formats using the active market's currency and format {{ price | money_with_currency }} — includes ISO code (e.g. "Rs. 1,500 PKR") {{ price | money_without_currency }} — number only {{ price | money_no_decimals }}

Asset & URL filters {{ 'theme.css' | asset_url | stylesheet_tag }} {{ 'app.js' | asset_url | script_tag }} {{ product.featured_image | img_url: '400x400', crop: 'center' }} {{ image | img_url: '800x' }} — width 800, auto height

String filters {{ 'My Product' | handleize }} → "my-product" {{ 'cart.title' | t }} — translation lookup {{ text | truncate: 100 }} {{ html | strip_html }} {{ text | newline_to_br }}

Array filters {{ products | where: "available", true }} {{ variants | map: "price" }} {{ products | sort: "title" }} {{ tags | join: ', ' }} {{ array | first }}, {{ array | last }}, {{ array | size }}

country_flag filter {{ 'PK' | country_flag }} → 🇵🇰 {{ 'AE' | country_flag }} → 🇦🇪 Takes a 2-letter ISO 3166-1 alpha-2 country code and returns the Unicode flag emoji.

Date filter {{ article.published_at | date: "%B %d, %Y" }} → "May 10, 2025" {{ 'now' | date: '%Y' }} — current year

Key Liquid tags - {% render 'snippet', var: value %} — include a snippet (no variable inheritance) - {% section 'name' %} — render a section - {% form 'product' %}...{% endform %} — form wrapper (product, contact, customer_login, create_customer, recover_customer_password, localization) - {% paginate collection.products by 24 %}...{% endpaginate %} - {% style %}...{% endstyle %} — outputs a style tag with dynamic values - {% layout none %} — skip the default layout - {% layout 'checkout' %} — use layout/checkout.liquid - {% liquid ... %} — multi-statement block without individual tag delimiters

Eekaam implements the full Shopify AJAX Cart API. Any Shopify theme JavaScript that calls these endpoints works without modification.

Endpoints - GET /cart.js — full cart JSON - POST /cart/add.js — add item (body: { id: variantId, quantity: 1 }) - POST /cart/change.js — change line item quantity - POST /cart/update.js — bulk update quantities - POST /cart/clear.js — empty cart - GET /products/:handle.js — product JSON - GET /collections/:handle/products.json — collection products - GET /search/suggest.json?q=term — predictive search - GET /recommendations/products.json?product_id=ID&limit=4 — recommendations

Important: prices are in cents cart.total_price and item.price are integers multiplied by 100 (same as Shopify). Divide by 100 to display.

Add to cart example fetch('/cart/add.js', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id: variantId, quantity: 1 }) })

Platform JS globals These are injected on every page inside {{ content_for_header }}: - window.Shopify.currency.active — active currency code (e.g. "PKR") - window.Shopify.locale — active locale (e.g. "en") - window.Shopify.routes.root — "/" - window.Eekaam.shop — store name - window.Eekaam.trackAddToCart(id, name, price) — fires all configured analytics pixels

When a store sells to multiple countries (e.g. UAE and Pakistan), the platform resolves a market for each request and adjusts prices automatically. Themes access this through the localization object.

Market resolution priority 1. market_id cookie (set when customer selects a country) 2. URL subpath or subdomain (e.g. /ae or ae.store.com) 3. Query param ?market=ID 4. Geo-IP from CF-IPCountry header 5. Primary market (fallback)

Prices are pre-resolved When a market is active, product.price is already in the market's currency with the correct exchange rate, adjustment, and rounding applied. Just call {{ product.price | money }}.

Using the localization object {{ localization.market.name }} — e.g. "UAE Market" {{ localization.market.currency.iso_code }} — e.g. "AED" {{ localization.country.iso_code }} — e.g. "AE" Loop markets: {% for market in localization.available_markets %}

Built-in country selector Drop {% render 'country-selector' %} anywhere in your layout. This renders a globe button that opens a modal listing all active markets with flag emojis. Only renders when there are 2 or more active markets. Selection sets a market_id cookie for 30 days.

Manually switching markets POST to /set-market with body { market_id: "uuid" } and Accept: application/json header. The server sets the cookie and returns JSON. Reload the page to show updated prices.

Validation rules summary Errors (block upload): missing layout/theme.liquid, missing templates/index.liquid, missing settings_schema.json, invalid JSON, external CDN links (except Google Fonts and GSAP), hardcoded API keys, images over 2 MB, total theme over 10 MB.

Warnings (should fix): missing product/collection/cart/404/search templates, missing header/footer sections, missing locales/en.json, unbalanced Liquid tags.