Headless PrestaShop con React y GraphQL: Guía 2025

Introducción: ¿Por qué Headless PrestaShop?

El comercio electrónico tradicional ha evolucionado. Los monolitos como PrestaShop, aunque potentes, a menudo limitan la flexibilidad del frontend. Aquí es donde entra en juego la arquitectura headless. Al separar el backend (PrestaShop) del frontend (React), obtenemos un control total sobre la experiencia de usuario, el rendimiento y la escalabilidad.

Este artículo te guiará en una implementación práctica de Headless PrestaShop utilizando React como frontend y GraphQL como capa de comunicación. Dejaremos atrás el clásico Smarty y montaremos una tienda moderna, rápida y desacoplada.

¿Qué necesitamos para empezar?

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

PrestaShop 1.7.x o superior (con el módulo GraphQL instalado y configurado).
Node.js 18+ y npm/yarn para el frontend React.
Conocimientos básicos de React, Apollo Client y GraphQL.
Un módulo GraphQL para PrestaShop (por ejemplo, el oficial de PrestaShop o soluciones como prestashop-graphql de la comunidad).

[WARNING] No uses versiones antiguas de PrestaShop (1.6 o inferior) sin migrar. El módulo GraphQL requiere al menos la 1.7.8 para funcionar correctamente.

Configuración del Backend: PrestaShop como API Headless

El primer paso es exponer los datos de PrestaShop a través de GraphQL. No necesitamos tocar el tema Smarty, solo activar y configurar el módulo.

Instalación del módulo GraphQL

Descarga e instala el módulo desde el marketplace oficial o desde el repositorio de la comunidad.
Actívalo y ve a la configuración (normalmente en Servicios Web > GraphQL).
Genera una API Key o token de acceso. Lo necesitarás para autenticar las peticiones desde React.

Endpoints y esquemas básicos

Una vez instalado, tu endpoint GraphQL será algo como:

https://tudominio.com/module/graphql/api

Puedes probarlo con una herramienta como GraphiQL o Altair. Por ejemplo, una query para obtener productos:

query {
  products {
    id
    name
    price
    cover {
      url
    }
  }
}

[TIP] Si el módulo no devuelve campos como cover, revisa la configuración del esquema. Algunos módulos requieren habilitar manualmente ciertos resolvers.

Construyendo el Frontend con React y Apollo Client

Con el backend listo, pasamos a crear el frontend moderno. Usaremos React con Apollo Client para consumir GraphQL.

1. Inicializar el proyecto React

npx create-react-app prestashop-headless
cd prestashop-headless
npm install @apollo/client graphql

2. Configurar Apollo Client

Crea un archivo apollo-client.js con la configuración básica:

import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';

const httpLink = createHttpLink({
  uri: 'https://tudominio.com/module/graphql/api',
  headers: {
    Authorization: `Bearer TU_API_KEY`,
  },
});

const client = new ApolloClient({
  link: httpLink,
  cache: new InMemoryCache(),
});

export default client;

3. Primer componente: Listado de productos

Vamos a crear un componente simple que muestre los productos usando useQuery.

import { useQuery, gql } from '@apollo/client';

const GET_PRODUCTS = gql`
  query {
    products {
      id
      name
      price
      cover {
        url
      }
    }
  }
`;

function ProductList() {
  const { loading, error, data } = useQuery(GET_PRODUCTS);

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

  return (
    <div className="product-grid">
      {data.products.map(product => (
        <div key={product.id} className="product-card">
          
          <h3>{product.name}</h3>
          <p>{product.price} €</p>
        </div>
      ))}
    </div>
  );
}

Implementación de Carrito y Checkout con GraphQL

Uno de los puntos críticos en una tienda headless es la gestión del carrito. PrestaShop expone mutaciones para crear, actualizar y leer carritos.

Crear un carrito

mutation {
  createCart {
    id
    token
  }
}

En React, usamos useMutation:

import { useMutation, gql } from '@apollo/client';

const CREATE_CART = gql`
  mutation {
    createCart {
      id
      token
    }
  }
`;

function AddToCartButton({ productId }) {
  const [createCart] = useMutation(CREATE_CART);

  const handleAdd = async () => {
    const { data } = await createCart();
    // Guardar token en localStorage o estado global
    localStorage.setItem('cartToken', data.createCart.token);
  };

  return <button onClick={handleAdd}>Añadir al carrito</button>;
}

[INFO] El token del carrito debe persistirse en el frontend (localStorage, cookies, etc.) para mantener la sesión del usuario.

Añadir productos al carrito

mutation addToCart($cartId: String!, $productId: Int!, $quantity: Int!) {
  addToCart(cartId: $cartId, productId: $productId, quantity: $quantity) {
    id
    items {
      product {
        name
      }
      quantity
    }
  }
}

Gestión del Estado Global y SEO

En un frontend headless, el SEO es un desafío porque React renderiza del lado del cliente. Para solucionarlo:

Next.js o Gatsby: Son frameworks React que ofrecen SSR (Server Side Rendering) o SSG (Static Site Generation). Son ideales para PrestaShop headless.
Apollo Client + SSR: Si usas Next.js, puedes usar getServerSideProps para precargar queries.

Ejemplo con Next.js:

export async function getServerSideProps() {
  const { data } = await client.query({
    query: GET_PRODUCTS,
  });

  return {
    props: {
      products: data.products,
    },
  };
}

Consideraciones de rendimiento y caching

GraphQL puede ser pesado si no se optimiza. Algunas prácticas recomendadas:

Fragmentos reutilizables: Define fragmentos para campos comunes (ej. productFields) y evita repetir queries.
Persisted Queries: Con Apollo, puedes usar consultas persistentes para reducir el payload.
CDN y caché: Usa un CDN para las imágenes de PrestaShop y configura cabeceras de caché en el backend.

Ejemplo de fragmento:

fragment productFields on Product {
  id
  name
  price
  cover {
    url
  }
}

query {
  products {
    ...productFields
  }
}

Despliegue y pruebas finales

Para desplegar tu tienda headless:

Compila el frontend: npm run build (o yarn build).
Configura un servidor web (Nginx, Apache, Vercel, Netlify) para servir los archivos estáticos.
Proxy inverso: Si tu frontend está en un dominio diferente, configura CORS en PrestaShop (módulo GraphQL suele tener opciones).
Prueba el flujo completo: Navegación, búsqueda, carrito y checkout.

[WARNING] No olvides probar el checkout con tarjetas reales en entorno de pruebas (sandbox) antes de ponerlo en producción.

Conclusión

La combinación de Headless PrestaShop con React y GraphQL te permite construir tiendas ultrarrápidas, con una experiencia de usuario personalizada y un mantenimiento más sencillo. Aunque la curva de aprendizaje es mayor que con el PrestaShop tradicional, los beneficios en rendimiento y flexibilidad son enormes.

Este enfoque no solo moderniza tu stack tecnológico, sino que te prepara para integrar futuras funcionalidades como PWA, aplicaciones móviles o incluso asistentes de voz. ¿Te animas a probarlo?