JSDoc을 활용한 Code n8n 노드용 TypeScript 인텔리센스 지원 - n8n 워크플로우

고급 n8n 사용자: 사용자 지정 로직 구현을 위해 n8n Code 노드를 자주 사용하는 개발자.
자동화 전문가: 강력한 디버깅 도구가 필요한 복잡한 n8n 워크플로우 시스템 구축자.
기술 콘텐츠 제작자: 효율적인 n8n 개발을 위한 모범 사례를 문서화하거나 공유하는 사람.
모든 사용자: n8n 템플릿 내 코드 품질을 개선하고 오류를 줄이고자 하는 모든 사용자.

JavaScript Code n8n 노드로 작업할 때, 적절한 자동 완성 기능 없이는 복잡한 입력 객체(예: n8n 노드나 API 작업에서 반환되는 객체)에 접근하고 디버깅하는 것이 까다로울 수 있습니다. 이 특정 n8n 워크플로우는 자바스크립트 생태계에서 널리 사용되는 방식인 JSDoc 주석을 활용하여 이 문제를 해결합니다.

n8n API 노드를 통해 검색된 Workflow` 객체와 같이 객체의 예상 구조를 정의함으로써, n8n 에디터의 기본 코드 기능에 강력한 타입 힌트를 제공할 수 있습니다. 이는 TypeScript 수준의 인텔리센스 결과를 제공하여, n8n 워크플로우 내에서 복잡한 사용자 지정 스크립트를 작성, 유지 관리 및 디버깅하는 작업을 훨씬 더 효율적이고 안정적으로 만듭니다. 이 기술은 강력한 n8n 템플릿의 개발 속도를 향상시키는 데 매우 중요합니다.

이 시연용 n8n 워크플로우는 인텔리센스 기술을 설명하기 위해 네 가지 주요 단계를 활용합니다.

1. 트리거 (Form submission 시): 프로세스는 기본적인 Form n8n 트리거를 사용하여 시작되며, 테스트를 위해 n8n 워크플로우를 수동으로 시작할 수 있게 해줍니다.


2. 워크플로우 데이터 가져오기 (Get This Workflow): n8n 노드가 get 작업을 사용하도록 구성되어 현재 실행 중인 n8n 워크플로우의 전체 메타데이터 구조를 검색합니다. 이 복잡한 JSON 객체는 다음 n8n 노드로 전달됩니다.


3. 인텔리센스 적용 (Code With Intellisense): 이 Code n8n 노드가 핵심적인 시연 부분입니다. 두 가지 JSDoc 타입 정의(@typedef {Object} Node 및 / @typedef {Object} Workflow /)를 정의합니다. 그런 다음 들어오는 JSON은 인라인 JSDoc 주석(/ @type {Workflow} /)을 사용하여 wf 변수에 캐스팅됩니다. 이 작업은 Code n8n 노드 내에서 wf.id, wf.name과 같은 속성에 접근하고 wf.nodes를 반복하는 데 완벽한 인텔리센스를 제공합니다.


4. 결과 표시 (Display Results): 마지막 Form n8n 노드는 방금 활성화된 인텔리센스를 사용하여 추출된 파싱된 출력을 정리된 HTML 형식으로 표시하여, 앞선 n8n 노드의 기능이 성공적인지 보여줍니다.

자체 n8n 템플릿에서 이 강력한 개발 기술을 설치하고 사용하려면 다음 단계를 따르세요.

1. 가져오기: 제공된 n8n 워크플로우 JSON을 복사하여 'JSON에서 가져오기(Import from JSON)' 옵션을 통해 n8n 인스턴스에 붙여넣습니다.


2. n8n API 자격 증명: 'Get This Workflow' n8n 노드는 n8n unio API v1이라는 이름으로 구성된 유효한 n8n API 자격 증명이 필요합니다. n8n에 활성 API 키가 설정되어 있는지 확인하세요.


3. 실행: 'On form submission' n8n 트리거를 실행하거나 n8n 워크플로우를 수동으로 테스트합니다. 편집 중인 'Code With Intellisense' n8n 노드를 관찰해 보세요. 객체 속성(예: wf.) 위로 마우스를 가져가거나 입력하면 이제 유용한 코드 제안이 표시됩니다.

On form submission (n8n 트리거): 이 n8n 워크플로우 테스트의 시작점 역할을 합니다. 표준 HTTP n8n 트리거 메커니즘입니다.
Get This Workflow (n8n 노드): 현재 실행 중인 n8n 워크플로우의 전체 JSON 표현을 검색하기 위해 내부 n8n API를 사용합니다. 이는 JSDoc 예제에 필요한 복잡한 객체 구조를 제공합니다.
Code With Intellisense (Code n8n 노드): 핵심 구성 요소입니다. JSDoc을 사용하여 복잡한 타입인 Workflow 및 Node 타입을 정의합니다. 핵심 설정은 인라인 캐스팅인 const wf = / @type {Workflow} / ($input.first().json);이며, 이는 n8n 템플릿 내에서 코드를 작성할 때 강력한 인텔리센스 기능을 활성화하는 데 필수적입니다.

• Display Results (Form n8n 노드): Code n8n 노드 실행 결과를 깔끔하게 포맷된 HTML 페이지로 출력하여 n8n 워크플로우 로직의 성공 여부에 대한 즉각적인 시각적 피드백을 제공합니다.