워크플로우를 춤추게 할 n8n 노드 개발: 디버깅부터 배포까지

D: 🚀 n8n으로 나만의 자동화 도구 만들기
n8n은 코드 한 줄 없이 워크플로우를 구축할 수 있는 오픈소스 자동화 툴입니다. 하지만 기본 제공 노드로는 구현이 어려운 기능이 있다면? 직접 노드를 개발해 보세요! 이 가이드에서는 n8n 커스텀 노드 개발의 A to Z를 상세히 설명합니다.

🔍 Part 1. 개발 환경 설정

필요한 도구

• Node.js (v14 이상)
• npm/yarn
• VS Code (추천)

# n8n 개발자 모드 활성화
git clone https://github.com/n8n-io/n8n.git
cd n8n
npm install
npm run build

💡 Tip: n8n-dev 패키지를 사용하면 더 쉽게 테스트 가능

import { NodeApi } from 'n8n-dev';

🛠 Part 2. 노드 기본 구조 이해

샘플 노드 코드 (TypeScript 기준)

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

export class MyCustomNode implements INodeType {
  description: INodeTypeDescription = {
    displayName: '🦄 유니콘 처리기',
    name: 'unicornProcessor',
    icon: 'fa:magic',
    group: ['transform'],
    version: 1,
    description: '유니콘 데이터를 변환하는 커스텀 노드',
    // ... 생략
  };
}

📌 핵심 구성 요소

• displayName: 워크플로우 편집기에 표시될 이름
• inputs: 노드의 입력 포트 수 (기본값: 1)
• outputs: 결과 출력 포트 수
• properties: 노드 설정 필드 정의

🐞 Part 3. 디버깅 기술

1. 콘솔 로그 활용

async execute(this: IExecuteFunctions): Promise {
  const items = this.getInputData();
  console.log('📦 Input items:', JSON.stringify(items, null, 2));
}

2. n8n 디버그 모드 실행

npm run start:dev -- --debug

3. Chrome DevTools 연결
chrome://inspect → “Open dedicated DevTools for Node” 선택

🚀 Part 4. 실전 예제: 날씨 API 노드 만들기

기능 요구사항

• 위치 입력 받기
• OpenWeatherMap API 연동
• 온도 단위 변환 기능

properties: [
  {
    displayName: 'Location',
    name: 'location',
    type: 'string',
    required: true,
    default: 'Seoul'
  },
  {
    displayName: 'Unit',
    name: 'unit',
    type: 'options',
    options: [
      { name: 'Celsius', value: 'metric' },
      { name: 'Fahrenheit', value: 'imperial' }
    ]
  }
]

📦 Part 5. 패키징 & 배포

1. npm 패키지로 배포

// package.json
{
  "name": "n8n-nodes-unicorn",
  "n8n": {
    "nodes": ["dist/nodes/UnicornProcessor/UnicornProcessor.node.js"]
  }
}

2. 로컬 설치 테스트

npm install /path/to/your/package

3. 공개 배포 시

• npm 레지스트리 퍼블리싱
• n8n 커뮤니티에 공유

🏆 성공적인 노드 개발을 위한 5가지 원칙

1. 명확한 에러 메시지 작성
   → “API 키가 유효하지 않습니다 (코드: 401)”
2. 타입 검증 강화

   if (typeof location !== 'string') {
    throw new Error('Location must be a string!');
   }

3. 성능 고려 (한 번의 API 호출로 여러 아이템 처리)
4. 설정 UI 직관성
5. 커뮤니티 피드백 수용

🔮 마치며

n8n 노드 개발은 자동화의 무한한 확장을 가능하게 합니다. 첫 노드 개발에는 2-3일이 소요될 수 있지만, 한 번 경험하면 기존 노드의 동작 원리를 깊이 이해하게 됩니다. 🎯

💬 도전해보세요!
“유튜브 자동 업로드 노드”나 “챗GPT 연동 노드”처럼 창의적인 아이디어를 구현해 보는 건 어떨까요? 여러분의 노드가 n8n 공식 저장소에 포함될 수도 있습니다!