@medusajs/framework and @medusajs/utils are first-party peer packages consumed heavily inside api/ and utils/. They must be present at the same major version as the installed @medusajs/medusa. No native build steps (pods, NDK) are required; this is a pure Node.js package.

Project setup

1. Drop the source. Place the contents of source/ at src/medusa-core/ (or any path you prefer) inside your TypeScript project.

2. tsconfig.json – enable decorators and path aliases:

   {
     "compilerOptions": {
       "experimentalDecorators": true,
       "emitDecoratorMetadata": true,
       "module": "CommonJS",
       "target": "ES2020",
       "strict": true,
       "paths": {
         "@medusa-core/*": ["./src/medusa-core/*"]
       }
     }
   }
   

3. Environment variables – create .env:

   DATABASE_URL=postgres://user:pass@localhost:5432/medusa
   REDIS_URL=redis://localhost:6379
   JWT_SECRET=your-jwt-secret
   COOKIE_SECRET=your-cookie-secret
   NODE_ENV=development
   

4. Entry point – load reflect-metadata before anything else, then use the loaders:

   import "reflect-metadata"
   import dotenv from "dotenv"
   dotenv.config()
   // import and invoke loaders from source/loaders/
   

5. Run migrations via the Commands export (see examples below) before starting the server.

Public API

Commands

import { Commands } from "@medusa-core/index"

// Commands is a namespace object:
// Commands.migrate(options)
// Commands.start(options)
// Commands.seed(options)

The Commands namespace aggregates every CLI command implementation from source/commands/. Use it to programmatically trigger database migrations, server start, or seeding within custom scripts or test harnesses without invoking the Medusa CLI binary.

buildPriceListResponse

import { buildPriceListResponse } from "@medusa-core/api/admin/price-lists/queries"

function buildPriceListResponse(
  priceLists: any[],
  apiFields: string[]
): AdminPriceListRemoteQueryDTO[]

Takes raw price-list records from the remote query (including nested price_list_rules and prices), normalises rules via buildPriceListRules, expands prices via buildPriceSetPricesForCore, and strips any fields not listed in apiFields using cleanResponseData. Call this in any custom admin route that returns price-list data to ensure consistent shape.

buildPriceListRules / buildPriceSetPricesForCore (via framework utils, re-used here)

import {
  buildPriceListRules,
  buildPriceSetPricesForCore,
} from "@medusajs/framework/utils"

const rules = buildPriceListRules(rawPriceList.price_list_rules)
const prices = buildPriceSetPricesForCore(rawPriceList.prices)

buildPriceListRules converts the raw join-table price_list_rules array into a flat key→value rule map. buildPriceSetPricesForCore flattens price-set money amounts into the core price shape expected by admin clients. Both are consumed inside buildPriceListResponse; call them directly when you need lower-level access.

Working examples

Scenario - Running database migrations programmatically

Invoke the built-in migrate command from application code instead of the CLI, useful in test setup or custom deploy scripts.

import "reflect-metadata"
import dotenv from "dotenv"
dotenv.config()

import { Commands } from "./src/medusa-core/index"

async function runMigrations() {
  await (Commands as any).migrate({
    directory: process.cwd(),
  })
  console.log("Migrations complete")
}

runMigrations().catch(console.error)

Scenario - Consuming buildPriceListResponse in a custom admin route

Wrap the helper in an Express handler to return normalised price-list data with only the fields your client needs.

import { Router, Request, Response } from "express"
import { buildPriceListResponse } from "./src/medusa-core/api/admin/price-lists/queries"

const router = Router()

router.get("/admin/custom/price-lists", async (req: Request, res: Response) => {
  // assume rawPriceLists fetched from remoteQuery
  const rawPriceLists: any[] = (req as any).priceLists ?? []

  const apiFields = [
    "id",
    "name",
    "status",
    "rules",
    "prices",
    "starts_at",
    "ends_at",
  ]

  const result = buildPriceListResponse(rawPriceLists, apiFields)
  res.json({ price_lists: result, count: result.length })
})

export default router

Scenario - Using promotion utils to validate rule attributes

The promotions utils expose operator maps and attribute validators used by the admin promotion engine. Reuse them in a custom promotion-rules validation service.

import {
  operatorsMap,
  validateRuleAttribute,
  validateRuleType,
} from "./src/medusa-core/api/admin/promotions/utils"

interface RuleInput {
  attribute: string
  operator: string
  type: string
  values: unknown[]
}

function validatePromotionRule(rule: RuleInput): string[] {
  const errors: string[] = []

  const attrError = validateRuleAttribute(rule.attribute)
  if (attrError) errors.push(attrError)

  const typeError = validateRuleType(rule.type)
  if (typeError) errors.push(typeError)

  if (!operatorsMap[rule.operator]) {
    errors.push(`Unknown operator: ${rule.operator}`)
  }

  return errors
}

const issues = validatePromotionRule({
  attribute: "customer.groups",
  operator: "in",
  type: "rules",
  values: ["vip"],
})

console.log(issues) // [] on valid input

File walkthrough

• index.ts – Re-exports Commands, all types, all utils, and all instrumentation symbols; the single entry point for external consumers.
• api/ – All Express route definitions and middleware; sub-divided by surface area (admin, store, auth, hooks, cloud) and by resource within each surface.
• api/middlewares.ts – Registers global middleware (authentication guards, body parsers, correlation-ID injection) on the Express app.
• api/utils/ – Shared request validators (common, products) used across multiple resource routes.
• commands/ – Implementations of migrate, start, seed, and other CLI sub-commands, consumed by index.ts as the Commands namespace.
• core-flows/ – Declarative workflow graphs for all major commerce operations; imported by route handlers to trigger multi-step transactional logic.
• feature-flags/ – Registry of toggleable feature flags read at boot time to gate experimental behaviour.
• instrumentation/ – OpenTelemetry span and metric setup; exported from index.ts for host apps to initialise tracing.
• loaders/ – Bootstrap logic that wires Express, the module container, plugins, scheduled jobs, and subscribers at server start.
• migration-scripts/ – One-off data-migration helpers run during version upgrades (not standard TypeORM migrations).
• modules/ – Local module registrations that override or extend @medusajs/framework defaults.
• policies/ – RBAC rule definitions evaluated by the auth middleware before requests reach route handlers.
• subscribers/ – Event-bus subscriber wiring; maps domain events to handler functions.
• types/ – Shared TypeScript interfaces and DTOs re-exported from the package root.
• utils/ – Low-level helpers such as cleanResponseData used throughout the API layer.

Common pitfalls and fixes

• Missing reflect-metadata import – Decorators silently fail at runtime; add import "reflect-metadata" as the very first line of your entry point.
• @medusajs/framework version mismatch – The API layer calls internal framework utils directly; pin @medusajs/framework to the exact same minor version as @medusajs/medusa in your package.json.
• DATABASE_URL not set before loaders run – Loaders read env vars synchronously at import time; call dotenv.config() before any import from this source (use a dedicated env.ts bootstrapper).
• ESM/CJS interop with TypeORM – Set "module": "CommonJS" in tsconfig.json; TypeORM decorators break under native ESM in Node.js <22.
• emitDecoratorMetadata missing – Entity relationship resolution fails silently; ensure both experimentalDecorators and emitDecoratorMetadata are true in tsconfig.json.
• Running migrations against a non-empty schema – Always take a database backup before running Commands.migrate; some migration-scripts are destructive and not reversible.

Vibe-coding prompt template

I have dropped the Medusa Commerce Backend core source into `src/medusa-core/`
(upstream package: `@medusajs/medusa`, domain: `backend`).
The integration reference is in `USAGE.md` at the project root.

Please help me integrate this source into my existing Node.js/TypeScript/Express
project step by step:

1. Read `USAGE.md` fully before writing any code.
2. Add the required dependencies from the "Required dependencies" section to
   my `package.json` and run `npm install`.
3. Update `tsconfig.json` with the settings in "Project setup".
4. Create a `.env` file with all variables listed in "Project setup".
5. Wire `src/medusa-core/loaders/` into my Express app entry point, ensuring
   `reflect-metadata` is the first import.
6. Add a migration script using `Commands` from `src/medusa-core/index.ts`.
7. Show me how to add a custom admin route that calls `buildPriceListResponse`
   from `src/medusa-core/api/admin/price-lists/queries`.
8. Point out any conflicts with my existing code and suggest fixes.

Use only the exports documented in `USAGE.md` - do not invent new APIs.

License and credit

Licensed under the MIT License. Source is part of the medusajs/medusa monorepo. Upstream npm package: @medusajs/medusa. See source/LICENSE if present in your copy of the source.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

eCommerce, Marketplace & POS Systems

$14.11