Skip to main content

Developer tools

Everything you need to build on Mercentia — the CLI for theme + app development, the headless storefront starter for custom Next.js storefronts, and the Storefront SDK that powers them both.

CLI
@mercentia/cli
v0.1 · workspace
Storefront SDK
@mercentia/storefront-sdk
React + composables
Headless starter
storefront-starter
Next.js 14 · in the monorepo
API keys
Manage
CLI authentication

CLI · theme + app development

shipped

The Mercentia CLI is the developer-facing equivalent of shopify / medusa CLIs. Sign in with an API key, pull / push theme files, scaffold a new app with OAuth + webhook boilerplate, trigger platform migrations from CI.

Install

pnpm add -g @mercentia/cli

Sign in

mercentia login        # paste an API key when prompted
mercentia whoami       # confirm

Generate the API key under Settings → API keys. Keys are hashed server-side; the CLI saves them to ~/.mercentia/credentials.json with mode 0600.

Common commands

mercentia store list                    # every store in the org
mercentia store use <id>                # pin a default for later calls
mercentia theme pull --dir my-theme     # download active theme
mercentia theme push --dir my-theme     # upload changes
mercentia theme dev --dir my-theme      # watch + push on save (debounced)
mercentia app create my-app             # scaffold a webhook-driven app
mercentia migration shopify             # trigger Shopify migration
                                        # (sources: shopify | bigcommerce |
                                        # woocommerce | squarespace |
                                        # magento | wix)

Every command accepts --host to target a staging gateway, and reads MERCENTIA_API_KEY / MERCENTIA_HOST from the environment so CI runners don't need the keychain file.

Headless storefront starter

Next.js 14 · App Router

A production-quality Next.js 14 storefront on top of the Storefront SDK. Server-component PDP / PLP rendering with edge runtime, multi-step checkout, customer account, JSON-LD structured data, the lot. Deploys to Vercel in one click.

  • Pages. / · /products/[handle] · /collections/[handle] · /cart · /checkout · /account · /search · /pages/[slug]
  • Theming. Tailwind with a clean default; tokens map to your store's brand.
  • Performance. Edge runtime on product / collection pages, next/image with srcset.
  • SEO. generateMetadata per route, JSON-LD for products + breadcrumbs.

Clone, then point the starter at your store with MERCENTIA_STORE_ID + MERCENTIA_STOREFRONT_TOKEN environment variables. The starter ships with the Storefront SDK already wired in for cart, checkout, search, and customer auth.

App marketplace

submission queue

Built an app you want merchants on Mercentia to install? Submit it through the marketplace queue. The Mercentia team reviews for security, scope hygiene, and merchant value; approved apps appear in /apps.

  1. Build with the CLI scaffold (mercentia app create).
  2. Publish your repo and run mercentia app publish.
  3. The Mercentia marketplace team reviews; you get an email on approve/reject.
  4. Approved apps surface in the store-facing app catalogue with revenue settlement to your developer payout account.