Fluctum Starter

       

Real-time dynamic pricing for Medusa — gold, silver, and any volatile-price asset.

→ Use this template on GitHub to create your own repository pre-wired with the Fluctum dynamic pricing plugin.

What's included

• Medusa backend (backend/) — pre-configured with @u11d/medusa-dynamic-pricing
• Next.js 16 storefront (storefront/) — live SSE price bar, dynamic cart, price-locked checkout
• Docker Compose — PostgreSQL 17 + Redis 8 for local development
• Turbo monorepo (pnpm workspaces) with dev / build / lint / test tasks

Prices update every few seconds from a live spot-price feed (goldapi.io or the built-in random provider for dev). They are displayed in real time via SSE and locked at checkout entry to protect both customer and merchant.

Prerequisites

• Node.js v24+
• pnpm v11+ (corepack enable to get the version pinned in package.json automatically)
• Docker & Docker Compose

Quick start

1. Use this template

Click Use this template on GitHub, or clone directly:

git clone https://github.com/u11d-com/fluctum_starter.git my-store
cd my-store

2. Install dependencies

Install workspace dependencies:

pnpm install

3. Configure environment variables

cp backend/.env.template backend/.env

For the storefront:

cp storefront/.env.template storefront/.env

4. Start infrastructure

docker compose up -d

PostgreSQL will be available on port 5432 (database: fluctum) and Redis on port 6379.

5. Run migrations (also seeds initial data)

pnpm run backend:migrate

6. Create admin user

pnpm run backend:create-admin

7. Start the backend

pnpm run backend:dev

Service	URL
Backend API	http://localhost:9000
Admin panel	http://localhost:9000/app

Log into the admin panel and confirm it loads correctly, then copy the Publishable API key (http://localhost:9000/app → Settings → API Keys) into storefront/.env:

NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...

8. Start the storefront

In a separate terminal, with the backend still running:

pnpm run storefront:dev

Service	URL
Storefront	http://localhost:8000

Once both are confirmed working, you can stop them and use pnpm run dev going forward to start backend + storefront together.

Deploy to Medusa Cloud

1. Push your repository to GitHub
2. Go to cloud.medusajs.com and connect your repo
3. Deploy — Medusa Cloud handles migrations, scaling, and SSL automatically

Plugin configuration

The plugin is configured in backend/medusa-config.ts:

import { randomProvider, createGoldApiProvider } from "@u11d/medusa-dynamic-pricing"

{
  resolve: "@u11d/medusa-dynamic-pricing",
  options: {
    materials: ["XAU", "XAG"],
    fetchIntervalSeconds: 10,
    priceLockDurationSeconds: 600,
    provider: process.env.GOLD_API_KEY
      ? createGoldApiProvider({ apiKey: process.env.GOLD_API_KEY })
      : randomProvider,
  },
}

See the plugin documentation for all options.

Scripts

Script	Description
pnpm run dev	Start backend + storefront in parallel
pnpm run backend:dev	Start only the backend (useful for first-run setup)
pnpm run storefront:dev	Start only the storefront
pnpm run build	Build all packages
pnpm run lint	Lint all packages
pnpm run test	Run all tests

License

MIT