1 How-to-run

Yen Nguyen edited this page 2025-10-16 15:43:00 +00:00

Table of Contents

• Development — Run both repos (Medusa backend + Next.js storefront)

Development — Run both repos (Medusa backend + Next.js storefront)

This workspace contains two repositories you run together:

• Medusa backend: vibentecit-store — see vibentecit-store/README.md and vibentecit-store/package.json

  • Key config: medusa-config.ts
  • Tests config: jest.config.js
  • Example scripts: vibentecit-store/src/scripts/README.md

• Next.js storefront: vibentecit-store-storefront — see vibentecit-store-storefront/README.md

  • Key files: next.config.js and check-env-variables.js (function: checkEnvVariables)

Use this guide to run both locally.

Prerequisites

• Node >= 18 (or the version your team enforces)
• Yarn (workspace uses Yarn in examples)
• A running Postgres/SQLite DB as configured by your env (see backend env vars in medusa-config.ts)

Quick setup (per-repo)

1. Backend (Medusa)

   • cd vibentecit-store
   • Copy env template and adjust: mv .env.template .env (or create .env with required vars referenced by medusa-config.ts)
   • Install deps:

     yarn
     

   • Seed (optional):

     yarn seed
     

     This runs medusa exec ./src/scripts/seed.ts as defined in package.json.
   • Start dev server:

     yarn dev
     

     This runs medusa develop and will serve the API (default port 9000 unless overridden).

2. Frontend (Next.js storefront)

   • cd vibentecit-store-storefront
   • Copy env template and adjust:

     mv [.env.template](http://_vscodecontentref_/1) [.env.local](http://_vscodecontentref_/2)
     

     Ensure you set at minimum the store connection keys (see checkEnvVariables — it validates NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY by default) and any Stripe keys if needed per README.md.
   • Install deps:

     yarn
     

   • Start dev server:

     yarn dev
     

     By default the storefront runs at http://localhost:8000 (see the storefront README).

Run both together

• Start the backend first (so the storefront can connect to the API).
• Start the storefront after the backend is up.

Common env notes

• The storefront uses NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY and optionally Medusa Cloud S3 vars (MEDUSA_CLOUD_S3_HOSTNAME, MEDUSA_CLOUD_S3_PATHNAME) referenced in next.config.js and validated by checkEnvVariables.
• The backend reads DB and CORS secrets from environment and from medusa-config.ts. Ensure DATABASE_URL, STORE_CORS, ADMIN_CORS, and JWT_SECRET/COOKIE_SECRET are set as needed.

Testing

• Backend tests use Jest. See jest.config.js. Run integration/unit tests from the backend repo: