Medusa

# Scaffolds a monorepo: apps/backend (server + admin) and apps/storefront (Next.js starter)
npx create-medusa-app@latest linen-shop --with-nextjs-starter --no-browser
# --no-browser exits after setup; without it the command keeps serving and opens the admin. Also: --db-url "$DATABASE_URL", --skip-db

cd linen-shop/apps/backend
npx medusa user -e ops@linenshop.dev -p "$MEDUSA_ADMIN_PASSWORD"   # create an admin user
npm run dev                              # medusa develop; keeps running, so use a second terminal for the rest
# API:        http://localhost:9000
# Admin:      http://localhost:9000/app
# Storefront: http://localhost:8000 (npm run dev in apps/storefront)

npx medusa db:migrate                    # after upgrading Medusa or adding modules and links
npx medusa db:generate brand             # generate a migration for a custom module named "brand"
npx medusa exec ./src/scripts/import-shopify.ts ./data/shopify-products.json   # run a script with the container

# Admin: exchange credentials for a JWT
TOKEN=$(curl -s -X POST http://localhost:9000/auth/user/emailpass \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"ops@linenshop.dev\",\"password\":\"$MEDUSA_ADMIN_PASSWORD\"}" | jq -r .token)

curl -s http://localhost:9000/admin/api-keys -H "Authorization: Bearer $TOKEN" \
  | jq -r '.api_keys[] | select(.type == "publishable") | .token'      # pk_fd8eefbf7...

# Store: every /store request carries the publishable key
curl -s "http://localhost:9000/store/products?limit=20" -H "x-publishable-api-key: $MEDUSA_PUBLISHABLE_KEY"
# without the header: 400 {"type":"not_allowed","message":"Publishable API key required ..."}

// src/api/admin/quick-product/route.ts — the file path is the URL: POST /admin/quick-product
// Routes under /admin require an authenticated admin user by default.
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { createProductsWorkflow } from "@medusajs/medusa/core-flows"

type QuickProductBody = { title: string; price: number; shipping_profile_id: string }

export async function POST(req: MedusaRequest<QuickProductBody>, res: MedusaResponse) {
  const { title, price, shipping_profile_id } = req.body
  const { result } = await createProductsWorkflow(req.scope).run({
    input: {
      products: [{
        title, status: "published", shipping_profile_id,
        options: [{ title: "Size", values: ["S", "M", "L"] }],
        variants: ["S", "M", "L"].map((size) => ({
          title: `${title} / ${size}`,
          sku: `${title.toUpperCase().replace(/\s+/g, "-")}-${size}`,
          options: { Size: size },
          prices: [{ amount: price, currency_code: "usd" }],   // major units: 39.5 means $39.50
          manage_inventory: false,
        })),
      }],
    },
  })
  res.json({ product: result[0] })
}

# The built-in route does the same; a product must define at least one option
curl -s -X POST http://localhost:9000/admin/products \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"title":"Linen Napkin Set","status":"published","options":[{"title":"Color","values":["Sand","Slate"]}]}'

# Storefront: prices are calculated per region, so pass region_id
curl -s "http://localhost:9000/store/products?region_id=$REGION_ID&fields=*variants.calculated_price" \
  -H "x-publishable-api-key: $MEDUSA_PUBLISHABLE_KEY"

// lib/checkout.ts — storefront checkout with the JS SDK (npm install @medusajs/js-sdk)
// Flow: cart → line items → email and address → shipping method → payment session → complete
import Medusa from "@medusajs/js-sdk"

export const sdk = new Medusa({
  baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL || "http://localhost:9000",
  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
})

export async function checkout(variantId: string, providerId = "pp_system_default") {
  const { regions } = await sdk.store.region.list()
  let { cart } = await sdk.store.cart.create({ region_id: regions[0].id })   // currency comes from the region
  ;({ cart } = await sdk.store.cart.createLineItem(cart.id, { variant_id: variantId, quantity: 2 }))
  ;({ cart } = await sdk.store.cart.update(cart.id, {
    email: "marta.keller@posteo.de",
    shipping_address: {
      first_name: "Marta", last_name: "Keller", address_1: "Lindenstrasse 14",
      city: "Berlin", postal_code: "10969", country_code: "de",
    },
  }))
  const { shipping_options } = await sdk.store.fulfillment.listCartOptions({ cart_id: cart.id })
  ;({ cart } = await sdk.store.cart.addShippingMethod(cart.id, { option_id: shipping_options[0].id }))
  // Creates the payment collection and the session; use "pp_stripe_stripe" for Stripe
  await sdk.store.payment.initiatePaymentSession(cart, { provider_id: providerId })
  const result = await sdk.store.cart.complete(cart.id)
  if (result.type !== "order") throw new Error(result.error.message)   // type "cart" = completion failed
  return result.order                                                  // { id: "order_01...", total: 30, ... }
}

// medusa-config.ts — add a modules array next to the scaffolded projectConfig
module.exports = defineConfig({
  projectConfig: { /* unchanged: databaseUrl, http.storeCors/adminCors/authCors, jwtSecret, cookieSecret */ },
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [{
          resolve: "@medusajs/medusa/payment-stripe",
          id: "stripe",
          options: {
            apiKey: process.env.STRIPE_API_KEY,
            webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
          },
        }],
      },
    },
  ],
})

// src/api/store/search/route.ts — GET /store/search?q=shirt
// Query reads data across modules; routes under /store require the publishable key.
import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
import { ContainerRegistrationKeys } from "@medusajs/framework/utils"

export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
  const { data: products, metadata } = await query.graph({
    entity: "product",
    fields: ["id", "title", "handle", "variants.sku", "variants.prices.amount", "variants.prices.currency_code"],
    filters: { title: { $ilike: `%${req.query.q ?? ""}%` }, status: "published" },
    pagination: { take: 20, skip: 0 },
  })
  res.json({ products, count: metadata?.count })
}

// src/subscribers/order-placed.ts — runs after an order is placed (email, ERP sync, warehouse notice)
// The event payload holds only the ID; load what you need with Query.
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"

export default async function orderPlacedHandler({ event: { data }, container }: SubscriberArgs<{ id: string }>) {
  const query = container.resolve(ContainerRegistrationKeys.QUERY)
  const { data: [order] } = await query.graph({
    entity: "order",
    fields: ["id", "display_id", "email", "total", "currency_code"],
    filters: { id: data.id },
  })
  if (!order?.email) return
  // Needs a Notification Module provider (SendGrid, for example) for the "email" channel; without one this call throws
  await container.resolve(Modules.NOTIFICATION).createNotifications({
    to: order.email, channel: "email", template: "order-confirmation",
    data: { display_id: order.display_id, total: order.total, currency_code: order.currency_code },
  })
}

export const config: SubscriberConfig = { event: "order.placed" }

// src/scripts/import-shopify.ts
import type { ExecArgs } from "@medusajs/framework/types"
import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
import { createProductsWorkflow } from "@medusajs/medusa/core-flows"
import { readFileSync } from "node:fs"

type ShopifyProduct = {
  title: string; handle: string; body_html: string
  options: { name: string; values: string[] }[]
  variants: { title: string; sku: string; price: string; option1: string }[]
}

export default async function importShopify({ container, args }: ExecArgs) {
  const query = container.resolve(ContainerRegistrationKeys.QUERY)
  const { data: [profile] } = await query.graph({ entity: "shipping_profile", fields: ["id"] })
  const { data: [channel] } = await query.graph({ entity: "sales_channel", fields: ["id"] })
  const { products } = JSON.parse(readFileSync(args[0], "utf8")) as { products: ShopifyProduct[] }
  for (let i = 0; i < products.length; i += 25) {
    const { result } = await createProductsWorkflow(container).run({
      input: {
        products: products.slice(i, i + 25).map((p) => ({
          title: p.title, handle: p.handle, description: p.body_html, status: "published" as const,
          shipping_profile_id: profile.id, sales_channels: [{ id: channel.id }],
          options: p.options.map((o) => ({ title: o.name, values: o.values })),
          variants: p.variants.map((v) => ({
            title: v.title, sku: v.sku, manage_inventory: false,
            options: { [p.options[0].name]: v.option1 },
            prices: [{ amount: Number(v.price), currency_code: "usd" }],   // "89.00" -> 89, not 8900
          })),
        })),
      },
    })
    console.log(`Imported ${i + result.length} of ${products.length} products`)
  }
}

npx medusa exec ./src/scripts/import-shopify.ts ./data/shopify-products.json
# Imported 25 of 500 products ... Imported 500 of 500 products