Crea tu propio nodo n8n: Guía paso a paso

Por / / 27 minutos de lectura

¡Hola, intrépido explorador del automatización! ¿Estás listo para llevar tus habilidades con n8n al siguiente nivel? Si ya te has sumergido en el fascinante mundo de la automatización y sientes que es hora de tener tu propio espacio, ¡has llegado al lugar correcto! Hoy vamos a desentrañar el misterio de cómo crear un nodo de n8n paso a paso. Prepárate para una aventura que te hará sentir como un verdadero mago de los flujos de trabajo.

Desde que n8n surgió como una alternativa robusta y de código abierto a herramientas como Zapier o Make (antes Integromat), ha ganado una comunidad enorme. Su versatilidad para conectarse con casi cualquier servicio web a través de sus nodos predefinidos es una maravilla. Pero, ¿qué pasa cuando necesitas conectar n8n con ese servicio super específico que solo tú o tu empresa usa? ¿O cuando quieres añadir una funcionalidad muy particular que no existe «de caja»? Ahí es donde entra en juego la creación de un nodo personalizado. Es como añadir una nueva herramienta a tu caja de Lego, ¡las posibilidades se multiplican!

La idea de construir un nodo puede sonar intimidante al principio, sobre todo si no eres un desarrollador full-stack con años de experiencia en JavaScript. Pero te prometo que, con un poco de guía y mucha curiosidad, verás que es más accesible de lo que parece. Vamos a desglosar este proceso en pasos manejables, explicando no solo el «cómo», sino también el «por qué» de cada decisión. Así, al final, no solo tendrás un nodo funcional, sino también una comprensión sólida de lo que estás haciendo.

¿Listo para codificar, aprender y quizás reír un poco en el camino? ¡Pues ajusta tu silla, toma tu bebida favorita y empecemos esta emocionante travesía hacia la personalización de n8n!

¿Por Qué Querrías Crear Tu Propio Nodo de n8n?

Antes de meternos de lleno en el código, es crucial entender las motivaciones detrás de la creación de un nodo personalizado. No se trata solo de «poder hacerlo», sino de resolver problemas reales y expandir las capacidades de tu plataforma de automatización. Piensa en n8n como un superhéroe con muchos poderes, pero a veces necesita un nuevo gadget para una misión muy específica. ¡Ese gadget es tu nodo!

  • Integraciones Específicas: Esta es la razón más común. Tal vez tu empresa utiliza un CRM interno, un sistema de gestión de proyectos muy particular, o una API propia para un servicio que no tiene un nodo en n8n. Crear un nodo personalizado te permite conectar n8n directamente a esos sistemas, automatizando flujos de trabajo que antes eran imposibles o requerían soluciones complejas. ¡Adiós a los scripts manuales y las exportaciones/importaciones de CSV!
  • Funcionalidad Mejorada: A veces, un nodo existente de n8n hace el 90% de lo que necesitas, pero hay un pequeño detalle, una opción, o una forma específica de manipular datos que simplemente no está implementada. En lugar de hacer mil pasos con nodos de «Function» para compensar, puedes crear tu propio nodo que haga exactamente lo que necesitas, de forma más eficiente y legible.
  • Optimización de Rendimiento: Aunque n8n es bastante eficiente, a veces la combinación de varios nodos para una tarea compleja puede añadir latencia o complejidad innecesaria. Un nodo bien diseñado puede encapsular toda esa lógica, ejecutándola de forma más rápida y con menos sobrecarga, especialmente si implica muchas llamadas a API o manipulaciones de datos intensivas.
  • Compartir con la Comunidad: Una de las grandes fortalezas de n8n es su comunidad de código abierto. Si creas un nodo que resuelve un problema común o se conecta a un servicio popular, ¡puedes contribuirlo al proyecto principal de n8n! Esto no solo te da reconocimiento, sino que ayuda a miles de usuarios más. Es una forma de «dar algo a cambio» al ecosistema.
  • Aprendizaje y Desarrollo Personal: Seamos honestos, a muchos nos gusta el desafío. Sumergirse en la creación de un nodo es una excelente manera de profundizar tus conocimientos en JavaScript (si aún no eres un experto), entender mejor cómo funcionan las APIs y cómo se estructura un proyecto de software. Además, ¿quién no quiere el orgullo de decir: «¡Ese nodo lo hice yo!»?

En resumen, crear un nodo de n8n no es solo un ejercicio técnico, es una estrategia para desbloquear todo el potencial de la automatización en tu contexto específico, ya sea personal o empresarial. Es el paso definitivo para pasar de ser un usuario de n8n a un verdadero arquitecto de automatizaciones. Ahora que tienes claras las razones, ¡vamos a ver qué necesitas para empezar!

Requisitos Previos: La Caja de Herramientas del Automatizador

Antes de que nos emocionemos demasiado y empecemos a teclear, necesitamos asegurarnos de que tienes las herramientas adecuadas en tu arsenal. Piensa en esto como preparar tu espacio de trabajo antes de un proyecto de carpintería: no querrás darte cuenta de que te falta el martillo a mitad de camino. No te preocupes, no necesitas un taller entero, solo unas pocas cosas esenciales.

  1. Conocimientos Básicos de JavaScript/TypeScript: Esto es fundamental. Los nodos de n8n se escriben principalmente en TypeScript (un superset de JavaScript que añade tipado estático, ¡lo cual es genial para proyectos grandes!), que luego se compila a JavaScript. No necesitas ser un gurú, pero entender conceptos como variables, funciones, objetos, promesas (async/await), y módulos (import/export) es crucial. Si esto te suena a chino, te recomiendo invertir un poco de tiempo en algún curso introductorio de JavaScript antes de sumergirte.
  2. Node.js y npm/yarn Instalados: n8n está construido con Node.js, y sus nodos también. Necesitarás tener Node.js instalado en tu máquina para ejecutar las herramientas de desarrollo y los scripts de compilación. Con Node.js viene npm (Node Package Manager), que usaremos para instalar dependencias y ejecutar comandos. Si prefieres yarn, también funciona perfectamente.

    • ¿Cómo lo instalo? Visita la página oficial de Node.js (nodejs.org) y descarga el instalador recomendado para tu sistema operativo. Sigue los pasos y ¡listo! Puedes verificar la instalación abriendo tu terminal y ejecutando node -v y npm -v (o yarn -v).
  3. Un Editor de Código (IDE): Si bien un Bloc de Notas técnico podría funcionar, te recomiendo encarecidamente un editor de código moderno. Visual Studio Code (VS Code) es el rey indiscutible para desarrolladores JavaScript/TypeScript, y es gratuito. Ofrece resaltado de sintaxis, autocompletado, depuración, integración con Git y muchas extensiones útiles.

    • Consejo Pro: Instala la extensión «ESLint» para VS Code. Te ayudará a mantener tu código limpio y a detectar errores antes de que se conviertan en dolores de cabeza.
  4. Terminal o Línea de Comandos: Para ejecutar comandos de Node.js, npm, Git y scripts de compilación, necesitarás una terminal.

    • En Windows: PowerShell o Git Bash (que viene con Git).
    • En macOS/Linux: La terminal por defecto funciona de maravilla.
  5. Git (Opcional, pero Recomendado): Si no lo tienes ya, ¡instálalo! Git es un sistema de control de versiones que te permite rastrear cambios en tu código, colaborar con otros y revertir a versiones anteriores si algo sale mal. Es una herramienta esencial en cualquier proyecto de desarrollo.
  6. Instancia de n8n (para Pruebas): Necesitarás una instancia de n8n funcionando para poder probar tu nodo. Puede ser una instancia local (la que ejecutas con n8n start), una Docker, o incluso una en la nube. Lo importante es que puedas acceder a ella y ver tu nodo en acción.
  7. Paciencia y Cafeína (o tu bebida preferida): No subestimes el poder de estos dos ingredientes. El desarrollo es un camino de prueba y error, y a veces las cosas no funcionan a la primera. ¡Mantén la calma y sigue adelante!

Una vez que tengas todo esto configurado y listo, estarás en una excelente posición para comenzar a codificar tu nodo. Si algo te falta, tómate un momento para instalarlo. ¡Mejor prevenir que lamentar! ¿Todo listo? ¡Excelente! Ahora, hablemos de la estructura de un nodo de n8n.

La Anatomía de un Nodo n8n: Entendiendo su Estructura

Cada nodo de n8n, ya sea uno predefinido o el que tú vas a crear, sigue una estructura bastante consistente. Entender esta arquitectura es clave para saber dónde colocar cada pieza de tu lógica. Piensa en ello como los planos de un edificio: necesitas saber qué va en cada habitación y cómo se conectan.

Un nodo de n8n se compone principalmente de dos archivos TypeScript cruciales, aunque hay otros archivos de soporte. Vamos a centrarnos en los dos principales:

1. El Archivo de Definición del Nodo (e.g., MyNewNode.node.ts)

Este archivo es el «cerebro» y la «interfaz» de tu nodo. Aquí defines cómo se ve el nodo en la interfaz de usuario de n8n (UI), qué opciones tiene, qué tipo de datos acepta y qué tipo de datos produce. Contiene metadatos y la lógica principal de ejecución.

Las secciones clave dentro de este archivo son:

  • Metadatos del Nodo (description):

    • displayName: El nombre legible del nodo que aparece en la UI (ej. «Mi Nodo Increíble»).
    • name: Un identificador único y en minúsculas para el nodo (ej. «miNuevoNodo»). Este se usa internamente.
    • icon: Opcional, pero genial para la UI. Puede ser un SVG, un Base64 o un icono de Font Awesome.
    • group: Categoría a la que pertenece el nodo (ej. «Transform», «Utilities», «Custom»).
    • version: La versión de tu nodo. ¡Importante para actualizaciones!
    • description: Una breve descripción de lo que hace el nodo.
    • defaults: Valores por defecto para la mayoría de los nodos.
    • inputs / outputs: Define cuántas entradas y salidas tiene el nodo (ej. 1 entrada, 1 salida).
    • credentials: Si tu nodo necesita autenticación (API Key, OAuth, etc.), aquí defines qué credenciales usará. n8n tiene un sistema robusto para manejar esto de forma segura.
  • Propiedades y Opciones (properties):

    Aquí es donde defines todos los campos que el usuario puede rellenar o seleccionar en la UI del nodo. Cada «propiedad» es un objeto que describe un campo de entrada.

    • displayName: Etiqueta del campo en la UI (ej. «ID del Recurso»).
    • name: Nombre interno del campo (ej. «resourceId»).
    • type: Tipo de control en la UI (string, number, boolean, options, collection, fixedCollection, multiOptions, json, etc.).
    • default: Valor por defecto del campo.
    • description: Texto de ayuda para el usuario.
    • required: Si el campo es obligatorio.
    • displayOptions: Controla cuándo se muestra este campo, basándose en el valor de otros campos (lógica condicional en la UI).
    • options: Si el tipo es options o multiOptions, aquí defines las opciones disponibles (name, value).
    • … y muchos más para casos avanzados como autocompletado, etc.
  • La Lógica de Ejecución (execute método):

    Esta es la «acción» de tu nodo. Es una función asíncrona que se ejecuta cada vez que el nodo recibe datos de entrada. Aquí es donde pondrás toda la lógica para:

    • Acceder a los datos de entrada.
    • Obtener los valores de las propiedades definidas por el usuario.
    • Realizar llamadas a APIs externas (usando librerías como axios).
    • Manipular datos.
    • Generar los datos de salida que pasará al siguiente nodo.

    El método execute recibe un contexto (this) que contiene información útil como las credenciales, métodos de ayuda (this.getNodeParameter(), this.sendOutputData()), y los datos de entrada.

2. El Archivo de Credenciales (e.g., MyApi.credentials.ts)

Si tu nodo necesita autenticarse con un servicio externo (por ejemplo, usando una clave API o tokens OAuth), defines la estructura de esas credenciales en un archivo separado. n8n se encarga de almacenar y gestionar estas credenciales de forma segura, y tu nodo solo las utiliza cuando las necesita.

  • displayName / name / description: Similar al nodo.
  • properties: Define los campos que el usuario debe rellenar para sus credenciales (ej. «API Key», «Client ID», «Client Secret»). Aquí también especificas el type (string, OAuth2, APIKey, etc.).

Entender esta estructura es el primer paso para organizar tu código de manera efectiva. No te preocupes si todo parece mucha información ahora mismo. Cuando empecemos a codificar, verás cómo cada parte encaja perfectamente. ¡Ya casi estamos listos para ensuciarnos las manos!

Paso 1: Configurando el Entorno de Desarrollo

Ahora que tenemos nuestra caja de herramientas lista y entendemos la anatomía de un nodo, es momento de configurar nuestro espacio de trabajo. n8n proporciona una excelente plantilla para iniciar proyectos de nodos, lo que nos ahorra mucho tiempo y nos asegura que la estructura inicial es la correcta. ¡Vamos a usarla!

1. Crea la Carpeta de Tu Proyecto

Primero, crea una carpeta donde vivirán tus nodos personalizados. Puedes llamarla n8n-nodes-custom o algo similar. Esta carpeta la mantendremos separada de la instalación principal de n8n.

Abre tu terminal y ejecuta:

mkdir n8n-nodes-custom
cd n8n-nodes-custom

2. Inicializa el Proyecto con la Plantilla de n8n

n8n tiene un generador de nodos que nos da un punto de partida excelente. Es como usar un asistente para crear un nuevo proyecto.

npm init n8n-node

Este comando te hará algunas preguntas. No te preocupes, puedes usar los valores por defecto o personalizarlos. Aquí hay una guía de las preguntas y posibles respuestas:

  • Package Name: n8n-nodes-mi-nodo (un nombre único para tu paquete, generalmente empieza con n8n-nodes-)
  • Node Display Name: Mi Nuevo Nodo (el nombre que verás en la interfaz de n8n)
  • Node Name: miNuevoNodo (el nombre interno del nodo, en camelCase)
  • Node Description: Este es un nodo de ejemplo personalizado.
  • Node Icon: (Puedes dejarlo en blanco por ahora o usar un SVG si tienes uno)
  • Node Category: Custom (o alguna de las categorías existentes como Communication, Data, etc.)
  • Credential Display Name: Mi Credencial (si tu nodo usa credenciales, este será su nombre)
  • Credential Name: miCredencial (el nombre interno de la credencial)
  • Credential Description: Credenciales para Mi Nuevo Nodo.
  • Credential Type: API Key (puedes elegir otros como OAuth2, Generic, etc. para este ejemplo, API Key es sencillo).

Después de responder a las preguntas, el generador creará una estructura de archivos básica para tu nodo y sus credenciales. ¡Ya tienes el esqueleto de tu nodo!

3. Instala las Dependencias

Una vez que el generador ha hecho su magia, navega a la nueva carpeta que se ha creado (normalmente con el mismo nombre que el Package Name que le diste, por ejemplo, n8n-nodes-mi-nodo) e instala las dependencias de Node.js:

cd n8n-nodes-mi-nodo
npm install

Esto instalará TypeScript, @n8n/types (que proporciona las interfaces para el desarrollo de nodos) y otras herramientas necesarias.

4. Entendiendo la Estructura Generada

Ahora, abre la carpeta n8n-nodes-mi-nodo en tu editor de código (VS Code es perfecto para esto). Verás una estructura similar a esta:

n8n-nodes-mi-nodo/
├── package.json
├── tsconfig.json
├── .eslintrc.json
├── .gitignore
├── README.md
├── src/
│   ├── credentials/
│   │   └── MiCredencial.credentials.ts  (Tu archivo de credenciales)
│   └── nodes/
│       └── MiNuevoNodo.node.ts          (Tu archivo de definición y lógica del nodo)
└── .prettierrc.json
  • package.json: Define tu proyecto, scripts (como build), y dependencias.
  • tsconfig.json: Configuración de TypeScript.
  • src/nodes/MiNuevoNodo.node.ts: Aquí es donde definiremos la interfaz de usuario y la lógica de ejecución de tu nodo.
  • src/credentials/MiCredencial.credentials.ts: Si elegiste crear credenciales, aquí se definirán.

5. Compila el Código

Antes de poder usar tu nodo, necesitas compilar el código TypeScript a JavaScript. Esto se hace con el script build:

npm run build

Esto creará una carpeta dist con los archivos JavaScript compilados. ¡Excelente! Tu nodo está «listo» para ser cargado en n8n.

En este punto, ya tienes un proyecto funcional con un nodo «Hello World» básico y, si lo configuraste, su respectiva credencial. El siguiente paso es decirle a n8n dónde encontrar este nodo para que puedas probarlo en un flujo de trabajo real. ¡Estamos progresando!

Paso 2: Desarrollando la Lógica del Nodo (El Core de la Acción)

Ahora que tenemos el esqueleto de nuestro nodo, es hora de darle vida. Vamos a editar el archivo src/nodes/MiNuevoNodo.node.ts (o como sea que lo hayas llamado) para añadirle funcionalidad real. Para este ejemplo, crearemos un nodo simple que toma un nombre como entrada y lo saluda de forma personalizada, y además, si usamos credenciales, podemos añadir un toque secreto.

1. Abriendo el Archivo del Nodo

Abre src/nodes/MiNuevoNodo.node.ts en tu editor de código. Verás algo similar a esto (simplificado):

import { INodeType, INodeTypeDescription } from 'n8n-workflow';

export class MiNuevoNodo implements INodeType {
    description: INodeTypeDescription = {
        displayName: 'Mi Nuevo Nodo',
        name: 'miNuevoNodo',
        icon: 'file:miNuevoNodo.svg', // Si generaste un SVG
        group: ['transform'],
        version: 1,
        description: 'Mi descripción de nodo.',
        defaults: {
            name: 'Mi Nuevo Nodo',
        },
        inputs: ['main'],
        outputs: ['main'],
        credentials: [
            // Aquí se referencian las credenciales
            {
                name: 'miCredencial', // El nombre de tu credencial
                required: false, // Opcional por ahora
            },
        ],
        properties: [
            // Propiedades del nodo
            {
                displayName: 'Nombre a Saludar',
                name: 'nameToGreet',
                type: 'string',
                default: 'Mundo',
                placeholder: 'Ingresa un nombre',
                description: 'El nombre al que el nodo debería saludar.',
            },
            {
                displayName: 'Mensaje Personalizado',
                name: 'customMessage',
                type: 'boolean',
                default: false,
                description: 'Define si se usa un mensaje personalizado.',
            },
            {
                displayName: 'Texto del Mensaje Personalizado',
                name: 'messageText',
                type: 'string',
                default: '¡Hola, {{name}}! Desde tu nodo personalizado.',
                placeholder: 'Escribe tu mensaje aquí',
                displayOptions: {
                    show: {
                        customMessage: [true],
                    },
                },
                description: 'El texto del mensaje personalizado. Usa {{name}} para el nombre.',
            },
            // ... otras propiedades
        ],
    };

    async execute(this: IExecuteFunctions): Promise {
        const items = this.getInputData();
        const returnData: INodeExecutionData[] = [];

        for (let i = 0; i < items.length; i++) {
            const nameToGreet = this.getNodeParameter('nameToGreet', i) as string;
            const customMessage = this.getNodeParameter('customMessage', i) as boolean;
            let message = '';

            if (customMessage) {
                const messageText = this.getNodeParameter('messageText', i) as string;
                message = messageText.replace('{{name}}', nameToGreet);
            } else {
                message = `¡Hola, ${nameToGreet}! ¡Qué buen día para automatizar!`;
            }

            // Opcional: Usar credenciales
            const credentials = await this.getCredentials('miCredencial'); // El nombre de la credencial
            if (credentials && credentials.apiKey) { // Suponiendo que tu credencial tiene una 'apiKey'
                message += ` (Con un toque secreto de la API Key: ${credentials.apiKey.substring(0, 5)}...)`;
            }

            returnData.push({
                json: {
                    greeting: message,
                    timestamp: new Date().toISOString(),
                },
            });
        }

        return this.prepareOutputData(returnData);
    }
}

2. Desglosando el Código del Nodo

Vamos a revisar las partes clave que hemos modificado o añadido:

  • description: INodeTypeDescription = { ... }:

    • Aquí hemos añadido más propiedades para nuestro nodo: nameToGreet (un string), customMessage (un booleano para activar/desactivar el mensaje personalizado), y messageText (el texto del mensaje si customMessage es true).
    • Nota el uso de displayOptions.show para messageText. Esto hace que el campo solo aparezca si customMessage está activado, ¡lo que hace la UI mucho más limpia y amigable!
    • En la sección credentials hemos añadido una referencia a miCredencial. Esto le dice a n8n que este nodo *puede* usar esa credencial.
  • async execute(this: IExecuteFunctions): Promise { ... }:

    Esta es la función principal donde ocurre la magia.

    • const items = this.getInputData();: Obtiene todos los elementos de entrada que el nodo recibió. n8n siempre procesa los elementos en lotes.
    • for (let i = 0; i < items.length; i++) { ... }: Iteramos sobre cada elemento de entrada. Es una buena práctica procesar los elementos uno por uno, especialmente si los nodos anteriores enviaron varios.
    • this.getNodeParameter('nameToGreet', i) as string;: Esta es la forma estándar de obtener los valores que el usuario introdujo en los campos de propiedades del nodo. El segundo parámetro i es importante para obtener el valor correcto si se procesan múltiples elementos. Usamos as string para tipar el valor, ya que getNodeParameter devuelve unknown.
    • Lógica Condicional: Hemos implementado una lógica simple para elegir entre un mensaje predeterminado o uno personalizado, usando el valor de customMessage.
    • messageText.replace('{{name}}', nameToGreet);: Un reemplazo simple para personalizar el mensaje. Podrías usar librerías más avanzadas para plantillas si necesitas algo más complejo.
    • Uso de Credenciales (Opcional):
      • const credentials = await this.getCredentials('miCredencial');: Aquí obtenemos las credenciales que el usuario configuró. El nombre 'miCredencial' debe coincidir con el name de tus credenciales y con lo que definiste en la sección credentials del nodo.
      • if (credentials && credentials.apiKey) { ... }: Verificamos si las credenciales existen y si tienen la propiedad apiKey (esto depende de cómo hayas definido tu credencial).
      • ¡Importante! Si tu credencial fuera de tipo OAuth2, la forma de acceder a los tokens y hacer peticiones sería diferente, usando, por ejemplo, this.get oAuth2Token() o configurando requestWithCredentials en el cliente HTTP.
    • returnData.push({ json: { ... } });: Para cada elemento de entrada, creamos un nuevo objeto JSON como salida. Es crucial que el resultado sea un array de objetos INodeExecutionData. Cada objeto INodeExecutionData debe tener una propiedad json y opcionalmente binary.
    • return this.prepareOutputData(returnData);: Este método prepara los datos para el siguiente nodo en el flujo de trabajo. Es una buena práctica usarlo.

3. Editando el Archivo de Credenciales (src/credentials/MiCredencial.credentials.ts)

Si tu nodo usa credenciales de tipo API Key, el archivo debería verse así:

import {
    ICredentialType,
    INodeProperties,
} from 'n8n-workflow';

export class MiCredencial implements ICredentialType {
    name = 'miCredencial';
    displayName = 'Mi Credencial API';
    documentationUrl = 'https://docs.ejemplo.com/mi-api-key'; // URL de la documentación de tu API
    properties: INodeProperties[] = [
        {
            displayName: 'API Key',
            name: 'apiKey',
            type: 'string',
            default: '',
            typeOptions: { password: true }, // Esto oculta el texto en la UI, ¡seguridad!
            description: 'La API Key para autenticarse con Mi Servicio.',
        },
        // Si necesitaras un "API Secret" u otro campo, lo añadirías aquí
        /*
        {
            displayName: 'API Secret',
            name: 'apiSecret',
            type: 'string',
            default: '',
            typeOptions: { password: true },
            description: 'El secreto para autenticarse.',
        },
        */
    ];
}

Aquí, definimos una propiedad apiKey de tipo string. typeOptions: { password: true } es importante para que n8n oculte el valor en la UI, tratándolo como una contraseña. ¡Siempre es bueno pensar en la seguridad!

4. Recompila el Nodo

Cada vez que hagas cambios en el código TypeScript, necesitarás recompilarlo a JavaScript:

npm run build

¡Felicidades! Acabas de escribir la lógica fundamental para tu nodo personalizado. El siguiente paso es ver cómo n8n puede encontrar y cargar este nodo para que puedas empezar a usarlo en tus flujos de trabajo.

Paso 3: Cargando Tu Nodo Personalizado en n8n

Has escrito el código, lo has compilado, ¡ahora es el momento de ver tu creación en acción! Para que n8n "vea" y cargue tu nodo personalizado, necesitamos indicarle dónde encontrarlo. Hay varias maneras de hacer esto, dependiendo de cómo ejecutes n8n.

Opción 1: Desarrollo Local (Usando N8N_DEV_PACKAGE_PATH)

Esta es la forma más común y fácil para el desarrollo y las pruebas locales. Le dice a n8n que busque nodos adicionales en una ruta específica.

  1. Configura la Variable de Entorno:

    Abre tu terminal y, antes de iniciar n8n, establece la variable de entorno N8N_DEV_PACKAGE_PATH para que apunte a la carpeta raíz de tu proyecto de nodo (donde está package.json).

    • En Linux/macOS: 
      export N8N_DEV_PACKAGE_PATH="/ruta/a/tu/n8n-nodes-mi-nodo"
n8n start

      Asegúrate de reemplazar /ruta/a/tu/n8n-nodes-mi-nodo con la ruta real de tu carpeta. Puedes usar pwd si estás dentro de la carpeta para obtener la ruta.

    • En Windows (CMD): 
      set N8N_DEV_PACKAGE_PATH="C:\ruta\a\tu\n8n-nodes-mi-nodo"
n8n start
    • En Windows (PowerShell): 
      $env:N8N_DEV_PACKAGE_PATH="C:\ruta\a\tu\n8n-nodes-mi-nodo"
n8n start

    Importante: Esta variable de entorno solo afecta a la sesión actual de la terminal. Si cierras la terminal, tendrás que volver a configurarla. Para una solución más permanente en desarrollo, podrías añadirla a tu .bashrc, .zshrc o similar, pero no es recomendable para producción.

  2. Inicia n8n:

    Si ya lo tenías iniciado, ciérralo y vuelve a iniciarlo después de establecer la variable de entorno. n8n detectará tu nodo al arrancar.

    n8n start

Ahora, cuando abras la interfaz de n8n en tu navegador (normalmente http://localhost:5678), deberías poder buscar tu nodo por su displayName (en nuestro ejemplo, "Mi Nuevo Nodo") y arrastrarlo a tu flujo de trabajo. ¡Voilà!

Opción 2: Instalación como Paquete npm (Para Producción o Compartir)

Esta opción es más adecuada cuando tu nodo está listo para ser usado de forma más permanente o para compartirlo. Instalas tu nodo directamente en el entorno de n8n.

  1. Empaqueta Tu Nodo (Opcional, si no lo tienes en un registro npm):

    Si tu nodo no está publicado en un registro npm público, puedes crear un paquete tarball (.tgz) desde tu carpeta de nodo. Desde la raíz de tu proyecto de nodo (n8n-nodes-mi-nodo):

    npm pack

    Esto creará un archivo n8n-nodes-mi-nodo-1.0.0.tgz (el nombre exacto dependerá de tu package.json) en la misma carpeta.

  2. Instala el Paquete en n8n:

    Navega a la carpeta de instalación de tu n8n (o a la carpeta donde se instalan los módulos de Node.js si usas Docker, ver más abajo) y usa npm para instalar tu nodo. Si usas la instalación de n8n por defecto (npm install n8n -g), la ubicación podría ser global.

    Si instalaste n8n globalmente:

    npm install -g /ruta/a/tu/n8n-nodes-mi-nodo

    O, si tienes el archivo .tgz:

    npm install -g /ruta/a/tu/n8n-nodes-mi-nodo-1.0.0.tgz

    Esto instala tu nodo como un módulo global de Node.js, lo que n8n puede encontrar.

    Si n8n no está instalado globalmente (por ejemplo, dentro de una carpeta específica de proyecto), navega a la carpeta node_modules de tu instalación de n8n y haz la instalación allí. También puedes añadir el paquete en el package.json de tu instalación de n8n y hacer npm install, pero esto es más avanzado.

  3. Inicia n8n:

    Una vez instalado, inicia n8n normalmente. Debería detectar tu nodo.

Opción 3: Con Docker

Si ejecutas n8n en Docker, la forma de cargar tu nodo es diferente, pero igual de efectiva.

  1. Crea tu nodo como un paquete npm: Sigue los pasos para empaquetar tu nodo en un archivo .tgz (npm pack).
  2. Crea un Dockerfile personalizado:

    En la misma carpeta donde tienes tu docker-compose.yml o donde configuras tu imagen de n8n, crea un Dockerfile que extienda la imagen oficial de n8n y añada tu nodo:

    # Usa la imagen oficial de n8n
FROM n8nio/n8n

# Copia el archivo .tgz de tu nodo al contenedor
# Asegúrate de que n8n-nodes-mi-nodo-1.0.0.tgz esté en la misma carpeta que tu Dockerfile
COPY n8n-nodes-mi-nodo-1.0.0.tgz /tmp/n8n-nodes-mi-nodo-1.0.0.tgz

# Instala el nodo usando npm dentro del contenedor
RUN npm install -g /tmp/n8n-nodes-mi-nodo-1.0.0.tgz

# Si tienes varias instancias de n8n, puedes querer limpiar
# RUN rm /tmp/n8n-nodes-mi-nodo-1.0.0.tgz
  3. Construye y Ejecuta la Imagen de Docker:

    Desde la carpeta donde está tu Dockerfile y el archivo .tgz:

    docker build -t mi-n8n-personalizado .
docker run -it --rm --name mi-n8n -p 5678:5678 mi-n8n-personalizado

    Si usas docker-compose, ajusta tu docker-compose.yml para construir tu imagen personalizada:

    version: '3.8'

services:
  n8n:
    build: . # Esto le dice a Docker Compose que busque un Dockerfile en la carpeta actual
    # image: n8nio/n8n # Ya no necesitas esta línea si estás construyendo tu propia imagen
    restart: always
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
    # ... otras configuraciones

volumes:
  n8n_data:

    Luego, reconstruye y levanta tus contenedores:

    docker-compose build
docker-compose up -d

Independientemente de la opción que elijas, una vez que n8n se inicie y cargue tu nodo, ¡estarás listo para crear flujos de trabajo con tu propia creación! Es un momento bastante gratificante. Ahora, ¡a probarlo!

Paso 4: Probando y Depurando Tu Nodo

¡El momento de la verdad ha llegado! Crear el código es solo la mitad de la batalla; la otra mitad es asegurarse de que funcione como esperamos (o al menos, de que no explote en nuestra cara). Las pruebas y la depuración son partes esenciales del ciclo de desarrollo de cualquier nodo de n8n.

1. Crea un Flujo de Trabajo de Prueba en n8n

Abre la interfaz de n8n en tu navegador (http://localhost:5678 si lo ejecutas localmente) y crea un nuevo flujo de trabajo.

  1. Añade un nodo "Start" o "Webhook": Esto servirá como el disparador de tu flujo.
  2. Busca tu nodo: En el panel de añadir nodos, busca el displayName de tu nodo (en nuestro ejemplo, "Mi Nuevo Nodo"). Arrástralo y suéltalo en el lienzo.
  3. Configura el nodo:

    • Haz doble clic en tu nodo.
    • Rellena los campos de propiedades (nameToGreet, customMessage, messageText).
    • Si tu nodo usa credenciales, haz clic en el selector de credenciales y crea una nueva (si no tienes una) o selecciona una existente. Rellena la API Key (puedes poner "TEST_KEY_123" por ahora).
  4. Conecta los nodos: Conecta el nodo "Start" o "Webhook" a la entrada de tu nodo.
  5. Añade un nodo "Set" o "NoOp" (Opcional): Puedes conectar la salida de tu nodo a un nodo "Set" o "NoOp" para inspeccionar fácilmente la salida. Esto es útil para ver los datos finales.

¡Tu primer flujo con tu nodo personalizado está listo!

2. Ejecuta el Flujo y Revisa la Salida

  1. Activa el flujo: Haz clic en "Activate" en la esquina superior derecha para habilitar tu flujo.
  2. Ejecuta manualmente: Puedes hacer clic en "Execute Workflow" si tu flujo comienza con un "Start", o activar el webhook si usaste uno.
  3. Inspecciona la salida: Una vez que el flujo termine, haz clic en tu nodo en el lienzo. En el panel de la derecha, verás las "Output Data" (Datos de Salida). Revisa que el JSON resultante contenga el saludo esperado y que los valores sean correctos.

3. Depuración (Cuando las Cosas Salen Mal)

Es muy raro que el código funcione a la primera. ¡No te frustres! La depuración es una habilidad esencial.

  • Mensajes de Consola (console.log): Esta es la forma más básica y efectiva. Puedes añadir console.log('Mi variable es:', myVariable); en tu método execute para imprimir valores en la terminal donde se ejecuta n8n.

    Consejo: Recuerda que después de cada cambio en el código, debes npm run build y reiniciar n8n para que los cambios surtan efecto (si usas N8N_DEV_PACKAGE_PATH).

  • Errores en n8n UI: Si tu nodo falla, n8n te mostrará un mensaje de error en la UI, a menudo con un "stack trace" (la secuencia de llamadas que llevó al error). Esto es invaluable para saber dónde se produjo el problema en tu código. Presta atención a los números de línea.
  • Depurador de VS Code: Para una depuración más avanzada (breakpoints, inspección de variables en tiempo real), puedes configurar VS Code para adjuntarse al proceso de Node.js de n8n.

    • Primero, inicia n8n en modo depuración. En lugar de n8n start, usa: 
      node --inspect-brk $(which n8n) start

      (La ruta a n8n puede variar).

    • En VS Code, ve a la pestaña "Run and Debug" (Ctrl+Shift+D).
    • Haz clic en "create a launch.json file" y selecciona "Node.js".
    • Ajusta la configuración para "Attach to Node Process". Necesitarás el puerto de depuración (generalmente 9229).
    • Coloca puntos de interrupción (breakpoints) en tu código haciendo clic a la izquierda de los números de línea.
    • Inicia la depuración en VS Code. Ahora, cuando tu flujo se ejecute, se detendrá en tus breakpoints.

    Esto puede ser un poco más complejo de configurar la primera vez, pero es una herramienta muy potente.

  • Manejo de Errores: Anticipa posibles errores (por ejemplo, llamadas a API que fallan, datos de entrada inválidos) y usa bloques try...catch en tu método execute. Puedes usar this.addOutputData(i, { error: e.message }) o lanzar un NodeOperationError para manejar los errores de forma elegante.

La depuración es un arte que se mejora con la práctica. No te desanimes si pasas más tiempo depurando que escribiendo código. ¡Es parte del proceso! Cada error resuelto te hace un mejor desarrollador de nodos. Con tu nodo funcionando y probado, ¡ya casi eres un experto en n8n!

Paso 5: Mejoras Avanzadas y Publicación (Llevando tu Nodo al Siguiente Nivel)

Has creado un nodo funcional, lo has probado y depurado. ¡Eso es un gran logro! Pero el viaje del nodo no tiene por qué terminar ahí. Hay muchas maneras de mejorar tu creación y, si te sientes aventurero, incluso compartirla con la comunidad de n8n.

1. Mejoras Avanzadas para Tu Nodo

  • Gestión de Errores Robusta: En el método execute, usa try...catch para manejar errores de forma elegante, especialmente al hacer llamadas a APIs externas. Puedes usar throw new NodeOperationError(this.getNode(), e.message); para que n8n muestre un error claro en el flujo.
  • Opciones Asíncronas (Autocompletado): Si tu nodo necesita cargar opciones dinámicamente (por ejemplo, una lista de proyectos de una API externa), puedes usar el tipo de propiedad resourceAll o options con una función de carga asíncrona. Esto permite que el nodo llame a una API para obtener una lista de opciones para un dropdown, mejorando la experiencia de usuario.

    Ejemplo de Autocompletado:

    {
    displayName: 'Proyecto',
    name: 'projectId',
    type: 'options',
    default: '',
    description: 'Selecciona el proyecto al que enviar la tarea.',
    typeOptions: {
        loadOptionsMethod: 'getProjects', // Llama a un método en la clase del nodo
    },
},

    Y luego, define el método getProjects en tu clase:

    methods: {
    async getProjects(this: ILoadOptionsFunctions): Promise {
        // Lógica para llamar a tu API y devolver un array de { name: '...', value: '...' }
        // Puedes usar this.getCredentials() aquí
        // return [{ name: 'Proyecto A', value: 'a123' }];
    },
},
  • Opciones de Lote (Batching): Si tu nodo va a manejar grandes volúmenes de datos, considera cómo procesa los lotes. n8n está diseñado para procesar elementos en lotes, y tu nodo debe ser eficiente al hacerlo.
  • Soporte para Modo Binario: Si tu nodo va a manipular archivos (imágenes, documentos), necesitarás usar el modo binario de n8n. Esto implica trabajar con el objeto binary en INodeExecutionData.
  • Internacionalización (i18n): Si planeas que tu nodo sea usado por una audiencia global, considera el soporte para múltiples idiomas. n8n tiene un sistema para esto, pero es más avanzado.
  • Documentación Clara: Añade un buen README.md en tu repositorio con instrucciones de instalación, uso y ejemplos. ¡Esto es oro puro para los usuarios!

2. Compartiendo y Publicando tu Nodo

Si has creado algo genial que crees que otros podrían usar, ¡considera compartirlo!

  • Publicar en npm: La forma más estándar de compartir módulos de Node.js es publicándolos en npm.

    • Asegúrate de que tu package.json esté bien configurado (nombre, versión, descripción, palabras clave, autor, licencia).
    • Necesitarás una cuenta en npmjs.com.
    • Desde la terminal, navega a la raíz de tu proyecto de nodo y ejecuta npm login.
    • Luego, npm publish --access public. Esto publicará tu paquete y estará disponible para que cualquiera lo instale con npm install -g n8n-nodes-tu-nodo.
  • Contribuir al Core de n8n: Si tu nodo se conecta a un servicio popular y crees que debería ser parte de la instalación por defecto de n8n, puedes abrir una "pull request" en el repositorio oficial de n8n en GitHub. El equipo de n8n revisará tu código, te dará retroalimentación y, si cumple con sus estándares, podría ser incluido. ¡Esto es un gran honor y contribución!
  • Crear un Repositorio GitHub: Incluso si no lo publicas en npm o en el core de n8n, tener un repositorio público en GitHub para tu nodo permite a otros encontrarlo, clonarlo y usarlo, o incluso contribuir.

Desarrollar un nodo personalizado para n8n es una habilidad poderosa. Te permite extender n8n de formas que de otro modo serían imposibles, integrarlo con cualquier sistema y optimizar tus flujos de trabajo. Desde el "hola mundo" hasta un nodo robusto y público, cada paso es una oportunidad de aprendizaje y una adición valiosa a tu arsenal de automatización. ¡Ahora, sal y crea cosas increíbles!

¡Vaya viaje hemos hecho, automatizador! Desde entender por qué querríamos un nodo personalizado hasta verlo correr en un flujo, hemos cubierto cada etapa de la creación. Hemos explorado la anatomía de un nodo, configurado nuestro entorno de desarrollo, escrito la lógica y, lo más importante, ¡aprendido a probar y depurar! Ahora tienes el conocimiento para expandir n8n a tus necesidades más específicas. Recuerda, la automatización es un superpoder, y con nodos personalizados, ¡eres el arquitecto de tu propio universo de eficiencia! ¡A automatizar!

Entradas relacionadas

Scroll al inicio