@jhrnandez/next-store

Módulo de tienda online con carrito, configuración y pedidos por WhatsApp para proyectos Next.js (Pages Router). Arquitectura hexagonal + DDD.

Instalación

npm install @jhrnandez/next-store

Integración rápida

1. Envolver _app.js con el provider

// src/pages/_app.js
import { StoreModuleProvider, FloatingCart } from '@jhrnandez/next-store';

export default function App({ Component, pageProps }) {
  return (
    <StoreModuleProvider>
      <Component {...pageProps} />
      <FloatingCart tenantName="mi-tienda" />
    </StoreModuleProvider>
  );
}

2. Crear las rutas de la tienda

Crea los archivos de página en el router de Next.js:

src/pages/[tenantName]/tienda/index.js — Catálogo paginado

import { StorePage } from '@jhrnandez/next-store';
import clientPromise from '@/lib/mongodb'; // o tu fuente de datos

export default function TiendaPage({ initialConfig }) {
  return <StorePage initialConfig={initialConfig} />;
}

export async function getServerSideProps({ params, req }) {
  // Construye la URL base desde la request para que funcione en cualquier entorno
  const protocol = req.headers['x-forwarded-proto'] || 'http';
  const host = req.headers['x-forwarded-host'] || req.headers.host;
  const baseUrl = `${protocol}://${host}`;

  return {
    props: {
      initialConfig: {
        tenantId: 'tu-tenant-id',
        apiUrl: `${baseUrl}/api/products`,
        tenantName: params.tenantName,
        storeName: 'Mi Tienda',
        whatsAppEnabled: true,
        whatsAppPhone: '521234567890',
        isValid: true,
      },
    },
  };
}

src/pages/[tenantName]/tienda/[slug].js — Detalle de producto

import { ProductDetailPage } from '@jhrnandez/next-store';

export default function ProductoPage({ initialConfig }) {
  return <ProductDetailPage initialConfig={initialConfig} />;
}

export async function getServerSideProps({ params, req }) {
  const protocol = req.headers['x-forwarded-proto'] || 'http';
  const host = req.headers['x-forwarded-host'] || req.headers.host;
  const baseUrl = `${protocol}://${host}`;

  return {
    props: {
      initialConfig: {
        tenantId: 'tu-tenant-id',
        apiUrl: `${baseUrl}/api/products`,
        tenantName: params.tenantName,
        storeName: 'Mi Tienda',
        whatsAppEnabled: true,
        whatsAppPhone: '521234567890',
        isValid: true,
      },
    },
  };
}

src/pages/cart.js — Carrito

import { CartPage } from '@jhrnandez/next-store';

export default function Carrito() {
  return <CartPage />;
}

3. API de productos

El módulo espera un endpoint GET /api/products que acepte los siguientes query params:

| Param | Tipo | Descripción | |---|---|---| | tenantId | string | ID del tenant | | page | number | Página (default: 1) | | limit | number | Productos por página (default: 20, máx: 100) |

Respuesta paginada:

{
  "products": [...],
  "total": 100,
  "totalPages": 5,
  "page": 1,
  "limit": 20
}

O array directo (sin paginación):

[{ "name": "...", "price": 100, ... }]

Cada producto debe tener:

{
  "_id": "mongo-id",
  "name": "Silla de madera",
  "price": 1500,
  "stock": 10,
  "category": "Sillas",
  "imageUrl": "https://...",
  "description": "...",
  "slug": "silla-de-madera",
  "tenantId": "tu-tenant-id"
}

4. Tailwind CSS (opcional)

Si usas Tailwind, agrega el source del módulo para que detecte sus clases:

/* src/styles/globals.css */
@source "../../node_modules/@jhrnandez/next-store/src";

5. next.config.mjs

El paquete usa CJS y necesita ser transpilado:

const nextConfig = {
  transpilePackages: ['@jhrnandez/next-store'],
};
export default nextConfig;

initialConfig — Campos

| Campo | Tipo | Requerido | Descripción | |---|---|---|---| | tenantId | string | ✅ | ID único del tenant | | apiUrl | string | ✅ | URL completa del endpoint de productos | | tenantName | string | ✅ | Slug del tenant (usado en la URL) | | storeName | string | — | Nombre visible de la tienda | | whatsAppEnabled | boolean | — | Habilita el botón de pedido por WhatsApp | | whatsAppPhone | string | — | Número con código de país (ej: 521234567890) | | isValid | boolean | ✅ | Debe ser true para que la tienda renderice |

Exportaciones disponibles

Páginas

• StorePage — Catálogo paginado con filtros y búsqueda
• ProductDetailPage — Detalle de producto
• CartPage — Carrito de compras
• StoreConfigPage — Página de configuración (panel admin)

Componentes

• FloatingCart — Botón flotante del carrito
• ProductCard — Tarjeta de producto reutilizable

Provider

• StoreModuleProvider — Provider combinado (Cart + Store context)
• CartProvider — Solo contexto del carrito
• StoreProvider — Solo contexto de configuración

Hooks

• useCart — Acceso al carrito (items, addItem, removeItem, etc.)
• useProducts — Fetch de productos paginados o por slug
• useStoreConfig — Configuración actual de la tienda

Licencia

MIT