Crear un nodo propio de n8n: estilo declarativo o programático
Cuándo compensa crear un nodo propio de n8n, qué estilo de construcción encaja y cómo instalarlo de forma privada, sin publicarlo.

Un nodo propio de n8n merece la pena cuando una integración se usa con tanta frecuencia que mantener siempre la misma configuración con el HTTP Request Node supone demasiado esfuerzo de mantenimiento. Según la documentación oficial de n8n, para construirlo hay dos estilos: el declarativo, que hoy es el estándar para los nodos nuevos, y el programático, necesario solo para nodos trigger, APIs que no son REST y procesamiento de datos complejo. Para uso interno, un nodo propio puede integrarse directamente en la instancia o empaquetarse como nodo privado en una imagen Docker propia, sin necesidad de publicarlo. Fecha de actualización: noviembre de 2026.
Estilo declarativo o programático: ¿qué enfoque encaja?
Para la mayoría de las integraciones basta con el estilo declarativo. Funciona con una sintaxis basada en JSON a través de la clave routing. Según la documentación de n8n, no necesita un método execute() propio y por eso se considera de menor mantenimiento y más preparado para el futuro.
- Estilo declarativo: Estándar para nodos nuevos, encaja con APIs REST, pero no admite nodos trigger.
- Estilo programático: necesario para nodos trigger, GraphQL u otras interfaces que no son REST, para nodos con dependencias externas y para transformaciones de datos complejas que van más allá del simple routing.
- Combinación permitida: Un paquete puede combinar un nodo de acción declarativo y un nodo trigger programático para el mismo servicio, también en nodos que se envíen para la verificación oficial.
La recomendación de la documentación es clara: quien no tenga ninguno de los casos especiales mencionados debe construir en estilo declarativo y tratar el programático como excepción.
¿Cómo se construye un nodo propio?
El punto de partida es la CLI de nodos de n8n, con la que se puede generar un proyecto a partir de una plantilla declarativa o programática. Se requieren conocimientos de JavaScript y TypeScript, un entorno de desarrollo propio con Git y nociones básicas de las estructuras de datos de n8n. La documentación ofrece tutoriales separados para ambos estilos, además de un linter de nodos para revisar el trabajo antes de que un nodo entre en producción.
¿Cómo se instala el nodo en la instancia propia sin publicarlo?
Para el uso interno es más adecuado instalarlo como nodo privado que publicarlo como Community Node. Para una instancia de n8n basada en Docker, la documentación describe este camino así:
- Compilación: En el proyecto del nodo, ejecutar
npm run buildy después la carpetadist/debe contener el nodo compilado junto con sus assets. - Imagen propia: Un Dockerfile basado en la imagen oficial de n8n copia
dist/a un directorio propio y define las variablesN8N_CUSTOM_EXTENSIONSyNODE_PATH. - Permisos: Los archivos del nodo deben ser legibles para el usuario
node, y el directorio de datos debe permitir escritura. - Dependencias: Si el nodo utiliza más que la dependencia en tiempo de ejecución
n8n-workflow, esos paquetes adicionales también deben estar en la imagen; de lo contrario, falta algo en tiempo de ejecución.
Estos detalles proceden de la guía oficial sobre nodos privados. Quien en cambio use n8n Cloud, según la documentación, no puede evitar el envío al repositorio público de la comunidad; un uso exclusivamente privado no está previsto allí.
¿Dónde encuentra límites el estilo declarativo en la práctica?
En la comunidad de n8n, los problemas con el estilo declarativo aparecen sobre todo en operaciones con archivos y datos binarios: varias publicaciones del foro describen que la subida de un archivo dentro de un nodo declarativo no funciona igual que en nodos comparables construidos de forma programática, y que sus autores acabaron cambiando al estilo programático. Esto coincide con la limitación oficial de que el procesamiento más complejo, más allá del simple routing, exige el estilo programático. Un segundo caso recurrente en los informes de instalación: tras integrar un nodo privado, este no aparece en la interfaz y no se muestra ningún mensaje de error; normalmente se debe a una ruta incorrecta o a permisos insuficientes, y no a un fallo del nodo en sí.
¿Merece la pena el esfuerzo para una pyme?
Para la mayoría de las automatizaciones en pymes basta con el HTTP Request Node o con una Community Node ya existente. Un nodo propio solo compensa cuando la misma integración se reutiliza en varios workflows y una interfaz limpia y mantenible reduce de forma notable el esfuerzo frente a varias configuraciones de HTTP Request. El coste del entorno de desarrollo, del proceso de compilación y de una imagen Docker propia es real y debe sopesarse frente al beneficio concreto, no frente al atractivo de la solución técnica. Quien no pueda o no quiera hacer esta valoración en su empresa puede recibir una evaluación en el marco de una consultoría de n8n de NordFlux.
Preguntas frecuentes sobre nodos propios de n8n
¿Necesito un nodo propio para cada nueva integración?
No. El HTTP Request Node cubre la mayoría de las integraciones REST sin necesidad de escribir ni mantener código. Un nodo propio solo compensa cuando la misma integración se usa de forma repetida en varios workflows.
¿Puedo usar un nodo propio sin publicarlo?
Sí, mediante la instalación como nodo privado. En una instancia Docker, eso significa una imagen propia con las variables de entorno N8N_CUSTOM_EXTENSIONS y NODE_PATH, sin que el nodo acabe en el repositorio público de la comunidad.
¿Qué estilo es más fácil para empezar?
El estilo declarativo, porque no hay que escribir ningún método execute() y la sintaxis JSON ofrece menos fuentes de error. Solo en nodos trigger, APIs que no son REST o procesamiento de datos complejo, según la documentación, no hay otra alternativa al estilo programático.
¿Funciona un nodo privado también en n8n Cloud?
Según la documentación actual, no en un entorno privado. En n8n Cloud, el envío como Community Node es la única vía prevista para usar un nodo propio.
Simon Glowik
Fundador de NordFlux. Siete años de experiencia, desde la web y el SEO hasta la automatización a escala de grupo, hoy de forma pragmática para las pymes y con soberanía de datos alemana.
Certificaciones
- Certificado Microsoft — PL-900 y AZ-900
- Certificado UiPath — Automation Developer Associate
¿Preguntas concretas sobre automatización o IA?
En una primera reunión gratuita de 30 minutos hablamos directamente de su caso. Sin compromiso.