Introducción

El nodo Code es una de las herramientas más poderosas en n8n. Cuando los nodos integrados como Set, Edit Fields o Split Out no pueden hacer exactamente lo que necesitas, el nodo Code te permite escribir JavaScript real para transformar los datos exactamente como quieres. Se ejecuta en un entorno Node.js en sandbox y tiene acceso directo a la estructura de ítems de n8n, brindándote control total sobre los datos de tu workflow.

Esta lección se enfoca en tres casos de uso prácticos: manipular arrays, formatear cadenas y calcular nuevos campos a partir de los existentes.

Cómo funciona el nodo Code

El nodo Code opera sobre el array de items que fluye a través de tu workflow. Cada ítem tiene un objeto llamado json que contiene sus datos. Cuando abres el nodo Code, escribes el cuerpo de una función — n8n lo envuelve automáticamente, por lo que no necesitas definir una función tú mismo.

Hay dos modos de ejecución. "Run Once for All Items" te da acceso a todos los ítems a la vez mediante la variable items. "Run Once for Each Item" te da una única variable item. El modo por defecto y más flexible es "Run Once for All Items", que es en el que se enfoca esta lección.

En este modo, tu código debe devolver un array de objetos con esta forma:

return [
  { json: { fieldName: value } },
  { json: { fieldName: value } }
];

Cada objeto en el array devuelto se convierte en un ítem de salida. Si devuelves un array vacío, no pasa ningún ítem hacia adelante.

Manipulación de arrays

Supón que un nodo upstream te da una lista de pedidos y cada ítem tiene un campo products que es un array de objetos. Quieres aplanar la lista para que cada producto se convierta en su propio ítem.

const result = [];

for (const item of items) {
  const orderId = item.json.orderId;
  const products = item.json.products;

  for (const product of products) {
    result.push({
      json: {
        orderId,
        productName: product.name,
        quantity: product.qty,
      }
    });
  }
}

return result;

Si empezaste con 3 ítems de pedidos, cada uno conteniendo 4 productos, terminas con 12 ítems de salida. Esto es algo que Split Out puede hacer en casos simples, pero el nodo Code te permite llevar el contexto calculado del ítem padre al mismo tiempo.

Para hacer lo contrario — agrupar varios ítems en uno — puedes usar reduce:

const grouped = items.reduce((acc, item) => {
  const key = item.json.category;
  if (!acc[key]) acc[key] = [];
  acc[key].push(item.json.productName);
  return acc;
}, {});

return Object.entries(grouped).map(([category, products]) => ({
  json: { category, products }
}));

Formateo de cadenas

Las transformaciones de cadenas son una razón habitual para recurrir al nodo Code. El editor de Expresiones maneja casos simples, pero el formateo en varios pasos queda más limpio en código.

Aquí tienes un ejemplo que normaliza un campo de nombre — elimina espacios en blanco, lo convierte a título y construye una etiqueta de visualización:

function toTitleCase(str) {
  return str
    .trim()
    .toLowerCase()
    .replace(/\b\w/g, (char) => char.toUpperCase());
}

return items.map((item) => {
  const raw = item.json.fullName || '';
  const formatted = toTitleCase(raw);
  const initials = formatted
    .split(' ')
    .map((w) => w[0])
    .join('');

  return {
    json: {
      ...item.json,
      fullName: formatted,
      initials,
      displayLabel: `${formatted} (${initials})`,
    }
  };
});

Usar el operador spread ...item.json mantiene todos los campos existentes y añade los nuevos encima, de modo que los nodos downstream siguen viendo los datos originales.

Cálculo de nuevos campos

El nodo Code es ideal cuando un nuevo campo depende de un cálculo que involucra varios campos existentes — cosas como totales, edad a partir de una fecha de nacimiento o flags de estado basados en reglas de negocio.

return items.map((item) => {
  const { unitPrice, quantity, discountPercent } = item.json;

  const subtotal = unitPrice * quantity;
  const discountAmount = subtotal * (discountPercent / 100);
  const total = subtotal - discountAmount;

  const status =
    total > 1000 ? 'high_value'
    : total > 200 ? 'standard'
    : 'low_value';

  return {
    json: {
      ...item.json,
      subtotal: +subtotal.toFixed(2),
      discountAmount: +discountAmount.toFixed(2),
      total: +total.toFixed(2),
      status,
    }
  };
});

Fíjate en el uso de +value.toFixed(2) — toFixed devuelve una cadena, por lo que el + unario la convierte de nuevo a número. Esto importa porque los nodos downstream que hagan operaciones matemáticas o comparaciones se comportarán de forma diferente con cadenas frente a números.

Errores comunes

Olvidar envolver la salida en json es el error más frecuente. Devolver { name: 'Alice' } en lugar de { json: { name: 'Alice' } } hará que n8n lance un error o descarte los datos silenciosamente.

Mutar item.json directamente en lugar de hacer spread puede causar efectos secundarios inesperados en algunas versiones de n8n — siempre construye un objeto nuevo.

Usar await sin marcar el nodo Code como compatible con async: si necesitas llamar a un helper integrado como $node o usar operaciones asíncronas, asegúrate de que tu lógica tenga en cuenta el modo de ejecución. Las transformaciones síncronas estándar como los ejemplos de arriba no necesitan ninguna configuración especial.

Por último, el nodo Code no tiene acceso a paquetes npm externos por defecto en n8n Cloud. En n8n autoalojado puedes añadir paquetes a una lista permitida, pero escribe tu código para que sea portable a menos que controles el despliegue.

Resumen

El nodo Code te ofrece un entorno JavaScript completo para manejar transformaciones que los nodos integrados no pueden expresar con limpieza. El hábito clave es devolver siempre un array de objetos { json: ... }, hacer spread de los campos existentes cuando solo quieras añadir nuevos y elegir "Run Once for All Items" cuando la transformación implique remodelar la colección en sí.