Integración Next.js con WooCommerce

Integración Next.js con WooCommerce (nextjs-woocommerce)

Manual operativo y lista de verificación para arquitecturar, consultar e integrar aplicaciones Next.js con App Router y un backend headless de WooCommerce a través de WPGraphQL, WooGraphQL y autenticación JWT.

---

Prerrequisitos y Referencias de Documentación

• Proyecto Next.js 14+ inicializado con App Router y TypeScript.
• Backend WooCommerce activo con WPGraphQL, WooGraphQL y wp-graphql-jwt-authentication.
• Para esquemas API completos y patrones de código de Next.js, consulta nextjs-woocommerce-reference.md.
• Para la implementación reutilizable del cliente de obtención de datos, consulta woocommerce-fetcher.ts.

---

Lista de Verificación de Implementación Paso a Paso

flowchart TD
    S1["1. Configuración de Entorno y Cliente"] --> S2["2. Catálogo de Productos Público (ISR/SSG)"]
    S2 --> S3["3. Autenticación de Usuarios (JWT + Cookies)"]
    S3 --> S4["4. Perfil Protegido e Historial de Pedidos"]
    S4 --> S5["5. Sesión de Carrito y Puente de Checkout Nativo"]

Fase 1: Configuración del Entorno y Cliente

• Configurar Variables de Entorno:
  • Agrega NEXT_PUBLIC_WORDPRESS_API_URL=https://tu-tienda.com/graphql a .env.example y .env.development.
  • Agrega NEXT_PUBLIC_WORDPRESS_URL=https://tu-tienda.com para las redirecciones de checkout.
• Configurar el Recuperador Universal:
  • Implementa woocommerce-fetcher.ts compatible con almacenamiento en caché ISR y encabezados de autenticación.

Fase 2: Catálogo Público de Productos y Taxonomías

• Navegación por Categorías: Consulta productCategories con hideEmpty: true para encabezados y menús de categorías.
• Archivo de Cuadrícula de Productos: Consulta products usando fragmentos de unión (... on SimpleProduct, ... on VariableProduct). Configura next: { revalidate: 300, tags: ['products'] }.
• Página de Detalle del Producto: Pre-renderiza rutas dinámicas (app/products/[slug]/page.tsx) con generateStaticParams() consultando todos los slugs de productos.

Fase 3: Pipeline de Autenticación JWT

• Mutación de Inicio de Sesión: Implementa una Acción de Servidor que ejecute login(input: { username, password }).
• Almacenamiento de Cookies: Almacena el authToken devuelto en una cookie HttpOnly segura (auth_token).
• Vinculación de Sesión: Si el cliente devuelve sessionToken, guárdalo en la cookie wc_session.
• Cierre de Sesión: Limpia las cookies de autenticación al cerrar sesión.

Fase 4: Datos y Pedidos de Usuario Protegidos

• Perfil del Cliente: Consulta viewer { id name email } pasando Authorization: Bearer <authToken>.
• Historial de Pedidos: Consulta customer { orders { nodes { id orderNumber total status } } } con cache: 'no-store'.

Fase 5: Gestión del Carrito y Estrategia de Checkout

• Estado del Carrito: Captura y persiste el encabezado woocommerce-session devuelto en las mutaciones addToCart.
• Puente de Checkout Nativo:
  • Redirige a los usuarios a https://tu-tienda.com/checkout para aprovechar las pasarelas de pago nativas de WooCommerce (ZarinPal, Mellat, Stripe), la logística regional y los sellos de cumplimiento sin necesidad de reescribir pasarelas personalizadas.

---

Casos Límite y Problemas Conocidos

1. Desoptimización Estática vs. Dinámica: Leer cookies en el diseño raíz o en las páginas de producto cambia Next.js al modo dinámico SSR completo. Solo lee cookies de autenticación dentro de Acciones de Servidor, Manejadores de Rutas o subárboles aislados del panel de cuenta (app/account/...).
2. Fragmentos Polimórficos: Las consultas directas como products { nodes { price } } fallarán en la validación en WooGraphQL. Siempre envuelve los precios y las variaciones en ... on SimpleProduct y ... on VariableProduct.
3. Pérdida de Sesión: Al agregar artículos al carrito, no reenviar el encabezado woocommerce-session crea un carrito vacío nuevo en cada mutación.
4. CORS en el Endpoint GraphQL: Asegúrate de que WordPress envíe los encabezados Access-Control-Allow-Origin y Access-Control-Allow-Headers: Authorization, Content-Type, woocommerce-session para tu dominio de Next.js.

---

Verificación y Pruebas Previas al Vuelo

• pnpm build se completa exitosamente con la generación estática de páginas de producto.
• Prueba que el formulario de inicio de sesión emita auth_token y redirija al panel de control.
• La página de cuenta muestra los detalles del cliente y la lista de pedidos con un token válido.
• Agregar al carrito actualiza el conteo de artículos del carrito en múltiples solicitudes del cliente.