Headless PrestaShop con Next.js y GraphQL: Arquitectura moderna 2025

¡Excelente! Vamos a construir un artículo técnico detallado sobre Headless PrestaShop con Next.js y GraphQL, optimizado para SEO y SysAdmins.

Introducción al Ecosistema Headless con PrestaShop

El comercio electrónico tradicional, con su arquitectura monolítica, está dando paso a modelos más flexibles y potentes. Headless PrestaShop representa la evolución natural de una de las plataformas de código abierto más populares del mundo. Al separar el frontend (la capa de presentación) del backend (la lógica de negocio y la base de datos), se abre un abanico de posibilidades en rendimiento, escalabilidad y personalización.

En este artículo, exploraremos cómo construir una tienda headless utilizando Next.js como framework de frontend y GraphQL como capa de comunicación con PrestaShop. Este stack no solo optimiza la velocidad de carga y la experiencia de usuario (UX), sino que también simplifica el mantenimiento y permite integrar funcionalidades modernas como Server-Side Rendering (SSR) y Static Site Generation (SSG).

[INFO] El enfoque headless no modifica el core de PrestaShop. Tu panel de administración, módulos de pago y lógica de negocio siguen intactos. Solo se sustituye el frontend clásico por una aplicación React/Next.js.

¿Por Qué Elegir Next.js para tu Frontend PrestaShop?

Next.js, el framework de React para producción, ofrece ventajas decisivas para un ecommerce:

Rendimiento Superior: Gracias al Server-Side Rendering (SSR) y la generación de páginas estáticas (SSG), las páginas se cargan más rápido. Google premia esto con un mejor posicionamiento.
SEO Optimizado: A diferencia de una SPA (Single Page Application) tradicional, Next.js renderiza HTML completo en el servidor, permitiendo a los crawlers indexar todo el contenido sin necesidad de JavaScript.
Experiencia de Desarrollo Moderna: Hot reloading, routing basado en archivos, soporte nativo para TypeScript y un ecosistema de plugins enorme.
Incremental Static Regeneration (ISR): Para catálogos de productos que cambian con frecuencia, ISR permite actualizar páginas estáticas sin tener que reconstruir todo el sitio.

### Comparativa: Frontend Clásico vs. Headless con Next.js

Característica	Frontend Clásico (Smarty)	Headless (Next.js + GraphQL)
Rendimiento	Limitado por el servidor monolítico	Máximo, con SSR/SSG/ISR
SEO	Bueno, pero menos controlable	Excelente, control total sobre meta tags y estructura
Personalización	Difícil, limitada por el tema	Ilimitada, con componentes React
Escalabilidad	Escalar el monolito es complejo	Frontend y backend escalan de forma independiente
Mantenimiento	Actualizaciones de PrestaShop pueden romper el tema	El frontend es independiente, menos riesgo

GraphQL: La Capa de Comunicación Perfecta para PrestaShop

La API tradicional de PrestaShop (WebService REST) está bien, pero es rígida y a menudo devuelve datos que no necesitas (over-fetching) o requiere múltiples llamadas para obtener información relacionada (under-fetching). GraphQL PrestaShop resuelve esto de forma elegante.

En lugar de múltiples endpoints, GraphQL expone un único punto de entrada. Tu frontend de Next.js puede consultar exactamente los datos que necesita en una sola petición.

Ejemplo de consulta GraphQL para obtener productos:

query GetProducts {
  products(pagination: { limit: 10, page: 1 }) {
    items {
      id
      name
      price {
        gross
        currency
      }
      cover {
        url
        alt
      }
      url
    }
    pagination {
      totalItems
      totalPages
      currentPage
    }
  }
}

[TIP] Para habilitar GraphQL en PrestaShop, puedes usar módulos como PrestaShop GraphQL API (de PrestaShop oficial) o PrestashopGraphQL de la comunidad. Ambos exponen un schema completo de tu tienda.

Preparando el Entorno: Requisitos y Configuración Inicial

Antes de escribir código, asegúrate de tener lo siguiente:

PrestaShop 8.x: Instalado y funcionando. Recomendamos una instalación limpia.
Módulo GraphQL: Instala y configura un módulo GraphQL (ej. prestashop-graphql).
Node.js 18+ y npm/yarn: Para el proyecto Next.js.
Editor de código: VS Code o similar.

### Configuración del Módulo GraphQL en PrestaShop

Ve a tu panel de administración de PrestaShop.
Ve a Módulos -> Catálogo de módulos.
Busca "GraphQL" e instala el módulo oficial de PrestaShop.
Configura el endpoint (normalmente https://tutienda.com/module/graphql/api).
Si tu tienda tiene protección por token, asegúrate de configurarlo en el módulo.

Creando el Proyecto Next.js para tu Headless PrestaShop

Ahora, crearemos la aplicación Next.js que consumirá la API GraphQL de PrestaShop.

### Inicialización del Proyecto

Abre tu terminal y ejecuta:

npx create-next-app@latest headless-prestashop --typescript --tailwind
cd headless-prestashop

### Instalación de Dependencias Clave

Necesitamos un cliente GraphQL. urql es ligero y excelente para SSR. También instalaremos graphql para el tipado.

npm install urql graphql

### Configuración del Cliente GraphQL

Crea un archivo lib/graphql-client.ts:

import { createClient, dedupExchange, fetchExchange } from 'urql';
import { cacheExchange } from '@urql/exchange-graphcache';

const API_URL = process.env.NEXT_PUBLIC_GRAPHQL_ENDPOINT || 'http://localhost:8080/module/graphql/api';

export const client = createClient({
  url: API_URL,
  exchanges: [dedupExchange, cacheExchange, fetchExchange],
  // Si tu API requiere token:
  // fetchOptions: () => ({
  //   headers: { authorization: 'Bearer ' + process.env.GRAPHQL_API_TOKEN },
  // }),
});

[WARNING] Nunca expongas tokens de API en el frontend. Usa variables de entorno con prefijo NEXT_PUBLIC_ solo para datos públicos. Para operaciones sensibles (carrito, login), crea un proxy API en Next.js.

Construyendo Componentes Esenciales: Productos y Categorías

Vamos a crear dos componentes clave: una lista de productos y una página de categoría.

### Componente de Lista de Productos

Crea components/ProductList.tsx:

import { useQuery } from 'urql';
import Link from 'next/link';

const PRODUCTS_QUERY = `
  query GetProducts($limit: Int!) {
    products(pagination: { limit: $limit, page: 1 }) {
      items {
        id
        name
        price {
          gross
          currency
        }
        cover {
          url
          alt
        }
        url
      }
    }
  }
`;

interface ProductListProps {
  limit?: number;
}

export default function ProductList({ limit = 8 }: ProductListProps) {
  const [result] = useQuery({ query: PRODUCTS_QUERY, variables: { limit } });
  const { data, fetching, error } = result;

  if (fetching) return <p>Cargando productos...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6">
      {data.products.items.map((product: any) => (
        <Link key={product.id} href={`/product/${product.id}`}>
          <div className="border rounded-lg p-4 hover:shadow-lg transition-shadow">
            
            <h3 className="text-lg font-semibold">{product.name}</h3>
            <p className="text-gray-700">{product.price.gross} {product.price.currency}</p>
          </div>
        </Link>
      ))}
    </div>
  );
}

### Página de Inicio (Home)

Modifica pages/index.tsx:

import ProductList from '../components/ProductList';

export default function Home() {
  return (
    <div className="container mx-auto px-4 py-8">
      <h1 className="text-3xl font-bold mb-8">Headless PrestaShop con Next.js</h1>
      <ProductList limit={12} />
    </div>
  );
}

Optimización y Rendimiento: SSR, SSG e ISR

El verdadero poder de Next.js PrestaShop reside en las estrategias de renderizado.

### Server-Side Rendering (SSR) para Páginas Dinámicas

Para una página de producto que necesita datos en tiempo real (stock, precio), usa getServerSideProps:

// pages/product/[id].tsx
import { client } from '../../lib/graphql-client';
import { gql } from 'urql';

const PRODUCT_QUERY = gql`
  query GetProduct($id: Int!) {
    product(id: $id) {
      id
      name
      description
      price { gross }
      images { url }
    }
  }
`;

export async function getServerSideProps(context: { params: { id: string } }) {
  const { id } = context.params;
  const result = await client.query(PRODUCT_QUERY, { id: parseInt(id) }).toPromise();
  return { props: { product: result.data.product } };
}

export default function ProductPage({ product }: any) {
  return (
    <div>
      <h1>{product.name}</h1>
      <div dangerouslySetInnerHTML={{ __html: product.description }} />
      <p>Precio: {product.price.gross}</p>
    </div>
  );
}

### Static Site Generation (SSG) + ISR para Catálogos

Para categorías con muchos productos, genera páginas estáticas en build time y actualízalas periódicamente con ISR:

// pages/category/[slug].tsx
export async function getStaticProps(context: { params: { slug: string } }) {
  // ... consulta GraphQL para obtener productos de la categoría
  return {
    props: { products: data.products.items },
    revalidate: 60, // ISR: regenera la página cada 60 segundos si hay solicitudes
  };
}

export async function getStaticPaths() {
  // ... consulta GraphQL para obtener todas las categorías
  const paths = data.categories.items.map((cat: any) => ({ params: { slug: cat.slug } }));
  return { paths, fallback: 'blocking' };
}

[INFO] Con fallback: 'blocking', las páginas de categorías nuevas se renderizan bajo demanda y se almacenan en caché para futuras visitas. Esto es ideal para catálogos en crecimiento.

Gestión del Carrito y Autenticación (Pistas)

Un ecommerce real necesita carrito y login. Aquí hay un enfoque práctico:

API Routes de Next.js: Crea rutas en pages/api/cart/add.ts para actuar como proxy.
Tokens de Sesión: Cuando un usuario inicia sesión en PrestaShop (a través de GraphQL), obtienes un token. Almacénalo en una cookie HTTP-only.
Operaciones de Carrito: Las mutaciones GraphQL para añadir/quitar productos deben incluir el token de sesión en el header.

Ejemplo de mutación para añadir al carrito:

mutation AddToCart($productId: Int!, $quantity: Int!) {
  addToCart(input: { productId: $productId, quantity: $quantity }) {
    id
    total
    items {
      product { name }
      quantity
    }
  }
}

Consideraciones de Seguridad y Buenas Prácticas

Protege tu Endpoint GraphQL: No expongas tu endpoint público directamente. Configura un proxy inverso (Nginx, Cloudflare) para limitar peticiones o añadir autenticación básica.
Validación de Datos: Siempre valida los datos en el backend de PrestaShop, no confíes solo en el frontend.
Rate Limiting: Implementa límites de peticiones para evitar abusos.
HTTPS: Obligatorio tanto en el frontend como en el backend.
Monitorización: Usa herramientas como Sentry para errores y Lighthouse para rendimiento.

[WARNING] Nunca ejecutes lógica de negocio sensible (cálculos de impuestos, descuentos) en el frontend. Siempre debe hacerse en PrestaShop.

Conclusión: ¿Merece la Pena el Cambio?

Implementar Headless PrestaShop con Next.js y GraphQL no es un proyecto trivial, pero las recompensas son enormes:

Velocidad de carga excepcional: Mejora el Core Web Vitals y la experiencia de usuario.
Flexibilidad de diseño: Libertad total para crear experiencias de compra únicas.
Escalabilidad independiente: Puedes escalar tu frontend y backend por separado según la demanda.
Preparación para el futuro: Este stack es moderno, tiene una comunidad enorme y es mantenido activamente.

Si tu tienda actual sufre por lentitud, tienes problemas de personalización o quieres diferenciarte de la competencia, este es el camino. Empieza con un prototipo, migra una categoría de prueba y mide los resultados. Te sorprenderá la diferencia.

[TIP] Para proyectos más pequeños, considera soluciones híbridas (ej. usar Next.js solo para el catálogo y mantener el frontend clásico para el checkout). Reduce el riesgo y el esfuerzo inicial.