RequireJS Fundamentals en Magento 2

The M2 JS Chaos

En Magento 2, RequireJS no es un capricho: es la capa que coordina carga asíncrona de módulos para evitar colisiones globales y orden de ejecución impredecible.

Si alguna vez viste JS que "a veces funciona" y "a veces no", normalmente faltó respetar el flujo AMD de Magento.

Warden Workflow

Antes de tocar código, asegura un ciclo de feedback rápido en local.

1. Trabaja en modo developer dentro de Warden para evitar cacheo agresivo de assets JS.
2. Si un cambio no aparece, limpia estáticos del theme específico dentro del contenedor.
3. Recarga y valida en Network que el archivo actualizado sale desde pub/static.

Warden Tip: para forzar regeneración de symlinks/estáticos del frontend en local:

warden shell
rm -rf pub/static/frontend/<Vendor>/<theme>/<locale>/*

Warden Tip: confirma modo developer para evitar comportamientos confusos con JS cacheado:

warden shell
bin/magento deploy:mode:show

Fase 1: define vs require

Primero aclara la base mental.

• define: crear herramientas (módulos reutilizables).
• require: usar herramientas (consumir módulos en tiempo de ejecución).

Analogía rápida: define es fabricar un taladro; require es tomarlo para perforar.

Ejemplo mínimo de define

define(['jquery'], function ($) {
  'use strict'

  return function (message) {
    console.log('Mensaje:', message)
    return $.trim(message)
  }
})

Ejemplo mínimo de require

require(['Vendor_Module/js/logger'], function (logger) {
  'use strict'

  logger('Hola desde require')
})

Fase 2: El mapa de navegación (requirejs-config.js)

Cuando ya entiendes define/require, pasas al enrutamiento de módulos.

Qué hace cada bloque

Ejemplo base:

var config = {
  map: {
    '*': {
      cartAdd: 'Magento_Catalog/js/catalog-add-to-cart'
    }
  },
  paths: {
    tinyLib: 'Vendor_Module/js/lib/tiny-lib'
  },
  shim: {
    tinyLib: {
      deps: ['jquery']
    }
  }
}

Jerarquía de carga

En este flujo, recuerda la jerarquía declarada para resolución de configuración: Base -> Theme -> Module.

Si hay conflicto de alias/config, revisa en ese orden para entender quién termina ganando en el merge final.

Fase 3: Mixins (el corazón del flujo)

En Magento 2, el enfoque limpio para extender JS core es Mixin: agregas comportamiento sin pisar archivo original. Si haces override directo, compras deuda técnica para cada upgrade.

Objetivo real: loggear Add to Cart sin override

1. Declaras el mixin en requirejs-config.js.
2. Extiendes el widget original con $.widget.
3. Agregas tu lógica y luego llamas this._super().

1) Declaración del mixin

var config = {
  config: {
    mixins: {
      'Magento_Catalog/js/catalog-add-to-cart': {
        'Vendor_Module/js/catalog-add-to-cart-mixin': true
      }
    }
  }
}

2) Implementación del mixin

define(['jquery'], function ($) {
  'use strict'

  return function (catalogAddToCart) {
    $.widget('mage.catalogAddToCart', catalogAddToCart, {
      submitForm: function (form) {
        console.log('[Mixin] Add to Cart ejecutado', form)
        return this._super(form)
      }
    })

    return $.mage.catalogAddToCart
  }
})

Por qué esto es importante

• No tocas core.
• Mantienes compatibilidad al actualizar Magento.
• El cambio es trazable y reversible.

Warden Tip: si el mixin no se refleja, limpia estáticos del theme y recarga con hard refresh (Disable cache en DevTools Network).

Fase 4: Debugging en el navegador

Cuando el cambio no aparece, depura carga antes de culpar el código.

1) Revisar carga en Network

• Abre DevTools -> Network -> filtra por JS.
• Confirma que tu archivo cargue desde pub/static/frontend/....
• Si ves 404 o archivo viejo, el problema es build/cache/ruta, no lógica del mixin.

2) Forzar carga desde consola

Para prueba rápida, invoca el módulo manualmente:

require(['Vendor_Module/js/catalog-add-to-cart-mixin'], function (mixin) {
  console.log('Mixin cargado:', typeof mixin)
})

Si esto falla, revisa alias/path/config antes de seguir.

Conclusión

RequireJS en Magento no es opcional: es el mapa de ejecución del frontend. Si sigues este flujo (Warden + config + mixins + debugging), puedes extender comportamiento sin romper core ni disparar deuda técnica.

Troubleshooting Cheat Sheet

Si quieres un frontend Magento estable: primero valida carga y mapeo, luego extiende con mixins, y recién después optimiza.