NexusV — Monorepo Medusa 2.0 + Next.js 14

Este repositorio contiene un monorepo listo para producción con:

• Backend con MedusaJS 2.x (API headless de comercio)
• Storefront con Next.js 14, Tailwind CSS y componentes de Medusa UI
• Integraciones opcionales: PostgreSQL, Redis, MinIO (archivos), MeiliSearch (búsqueda), Stripe (pagos), Resend/Sendgrid (emails)

Si quieres desplegar rápidamente en la nube, puedes usar el template de Railway: Deploy con un clic.

---

Requisitos

• Node.js 22.x
• pnpm 9.x o npm 10.x
• Servicios (locales o gestionados):
  • PostgreSQL (requerido para datos)
  • Redis (recomendado para colas/flows; si no se configura, se omite)
  • MinIO (opcional; si no se configura, se usa almacenamiento local)
  • MeiliSearch (opcional para búsqueda)

---

Estructura

• backend/: API de Medusa, configuración de módulos e integraciones
• storefront/: Aplicación Next.js 14 (App Router)

---

Configuración rápida (local)

1. Backend

cd backend
pnpm i
cp .env.template .env

# Mínimo: URL de base de datos y secretos
# DATABASE_URL=postgres://usuario:password@localhost:5432/mi_bd
# JWT_SECRET=un_secreto_seguro
# COOKIE_SECRET=otro_secreto_seguro
# BACKEND_URL=http://localhost:9000

# Inicializar datos del sistema (migraciones + seed requerido)
pnpm ib

# Desarrollo
pnpm dev
# Admin UI: http://localhost:9000/app

2. Storefront

cd storefront
pnpm i
cp .env.local.template .env.local

# Requerido para arrancar
# NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...

# Desarrollo (espera al backend antes de arrancar)
pnpm dev
# Storefront: http://localhost:8000

Abre dos terminales, una para backend y otra para storefront.

---

Variables de entorno (principales)

• Backend (backend/.env):

  • Obligatorias típicas: DATABASE_URL, JWT_SECRET, COOKIE_SECRET, BACKEND_URL
  • CORS: ADMIN_CORS, STORE_CORS, AUTH_CORS
  • Redis (opcional): REDIS_URL
  • Almacenamiento MinIO (opcional): MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_BUCKET
  • Búsqueda Meili (opcional): MEILISEARCH_HOST, MEILISEARCH_ADMIN_KEY
  • Pagos Stripe (opcional): STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET
  • Email (opcional):
    • Sendgrid: SENDGRID_API_KEY, SENDGRID_FROM_EMAIL
    • Resend: RESEND_API_KEY, RESEND_FROM_EMAIL

• Storefront (storefront/.env.local):

  • Requerida: NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY
  • Otras comunes: NEXT_PUBLIC_BASE_URL (por defecto https://localhost:8000)

---

Scripts útiles

• Backend:

  • pnpm ib: inicializa el backend (migraciones + seed de datos de sistema)
  • pnpm dev: arranca en desarrollo (API + Admin en localhost:9000/app)
  • pnpm build && pnpm start: compila y ejecuta desde código compilado
  • pnpm seed: ejecuta el seed de ejemplo

• Storefront:

  • pnpm dev: arranca el storefront con recarga en caliente
  • pnpm build / pnpm start: compila y ejecuta producción
  • pnpm test-e2e: tests E2E con Playwright (si es la primera vez: npx playwright install)

---

Despliegue

• Railway (recomendado para demo): Template con un clic
• Variables de entorno se autoconfiguran en gran parte si usas el template. Para despliegues manuales, replica las variables listadas arriba en tu proveedor.

---

Integraciones incluidas (opcionales)

• Archivos: MinIO o almacenamiento local (según variables presentes)
• Búsqueda: MeiliSearch
• Pagos: Stripe
• Email: Sendgrid o Resend (con plantillas React Email)

Consulta los READMEs específicos en backend/src/modules/** para detalles.

---

Solución de problemas

• Asegúrate de que DATABASE_URL es accesible desde tu máquina.
• Si el backend no levanta, revisa JWT_SECRET, COOKIE_SECRET y CORS.
• Si el storefront no arranca, define NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY en .env.local.
• Stripe/Meili/MinIO requieren sus variables correspondientes; si no están, el backend usará alternativas o desactivará el módulo.

---

Hecho con MedusaJS y Next.js. Para más información consulta la documentación de Medusa y Next.js.