ecom_admin Local Development Guide

Overview

The ecom_admin is a standalone Cloudflare Worker website for merchant-facing search UI customization. It provides a Rebuy-style visual editor with color pickers, sliders, drag-to-reorder lists, and live preview.

Prerequisites

• Node.js 18+
• npm
• Wrangler CLI (npm install -g wrangler)

Quick Start

cd components/ecom_admin
npm install
npm run dev

Opens at http://localhost:5173. Enter any API key string to log in (validation is stubbed in local dev).

Full E2E Testing (with Shopify app + storefront)

Terminal 1: Shopify App (admin server + admin UI)

cd components/shopify
shopify app dev --config shopify.app.raynorchavez.toml

This starts the admin server on http://localhost:8000 and the Shopify admin UI.

Terminal 2: ecom_admin Visual Editor

cd components/ecom_admin
npm run dev

Opens at http://localhost:5173.

Connecting ecom_admin to the local admin server

The Shopify CLI assigns a random port to the FastAPI server each time. Find it:

lsof -i -P -n | grep python | grep LISTEN

Look for the python process listening on a port (e.g., 50368). Then create/update .dev.vars:

# components/ecom_admin/.dev.vars (gitignored)
ENV=local
ADMIN_SERVER_BASE_URL=http://localhost:50368

The base URL is passed to the browser via a root route loader and React Context — no manual window assignment needed.

Testing the full flow

1. Start both servers (Terminal 1 + Terminal 2)
2. Open your Shopify dev store admin → Apps → Marqo
3. Open ecom_admin at http://localhost:5173
4. Log in with your Marqo API key
5. Change a setting (e.g., enable CTA button, change sale badge color)
6. Click Save → hits POST /api/v1/storefront/shops/{shop_id}/settings → writes to DynamoDB + Shopify metafields
7. Reload your dev store's search page (/search?q=something)
8. The storefront widget reads updated settings from the metafield and renders accordingly

Architecture

ecom_admin (localhost:5173)
  → GET /api/v1/storefront/shops (Marqo API key → list shops)
  → GET /api/v1/storefront/shops/{shop_id}/settings (load settings)
  → POST /api/v1/storefront/shops/{shop_id}/settings (save settings)
      → admin_server (localhost:8000)
        → DynamoDB write
        → Shopify metafield write (via stored OAuth token)
        → DDB stream → settings exporter → Cloudflare KV
      → Storefront widget reads from metafield/KV on page load

Available Scripts

Command	Description
npm run dev	Start dev server with hot reload
npm run build	Build for production
npm run preview	Preview production build
npm run typecheck	Run TypeScript type checks
npm run format	Auto-format code (Biome + Prettier)
npm run lint	Check code quality
npm run test	Run tests
npm run deploy	Deploy to dev environment
npm run deploy:staging	Deploy to staging
npm run deploy:prod	Deploy to production

Settings Sections

The visual editor has 9 settings sections matching Rebuy Smart Search's pattern:

1. Layout — search bar toggle, placeholder text, page title template
2. Filters — drag-to-reorder list, icon style, product count, collapse behavior, filter mode (sidebar/drawer)
3. Sorting — drag-to-reorder options, default sort, custom labels
4. Product Display — image ratio, carousel toggle, column breakpoints, spacing, alignment, sale badge (colors/position/text), price display colors
5. Call to Action — enable toggle, button text per state, behavior (navigate/add-to-cart), colors, border, radius
6. Pagination — items per page, per-page dropdown toggle
7. Product Reviews — provider (Okendo/Trustpilot/Custom), metafield config, star styling
8. Selectors — single "Embedded Element" CSS selector (like Rebuy's)
9. Custom CSS — global CSS override editor

Key Files

File	Purpose
app/routes/_index.tsx	Login page (API key entry)
app/routes/editor.tsx	Main editor layout with SettingsProvider
app/routes/editor.$section.tsx	Section detail dispatcher
app/contexts/settings-context.tsx	React Context for settings state
app/hooks/use-settings.ts	Settings fetch/save hook with API integration
app/hooks/use-auth.ts	API key auth state (localStorage)
app/lib/settings-converter.ts	Backend ↔ frontend format converter
app/lib/api-client.ts	HTTP client for admin_server API
app/lib/types.ts	TypeScript interfaces for all settings
app/components/settings/	All 9 settings section components
app/components/ui/	Shared UI primitives (ColorPicker, Slider, SortableList, etc.)
wrangler.toml	Cloudflare Worker deployment config

Deployment

Environment URLs

Environment	URL
Dev	dev-ecom-admin.dev-marqo.org
Staging	staging-ecom-admin.dev-marqo.org
Production	ecom-admin.marqo.org

Setting secrets

For staging/production, ADMIN_SERVER_BASE_URL must be set as a Wrangler secret:

wrangler secret put ADMIN_SERVER_BASE_URL --env staging
wrangler secret put ADMIN_SERVER_BASE_URL --env prod