안녕하세요, 자동화와 워크플로우 효율성에 관심 많은 여러분! 오늘은 n8n을 더욱 강력하게 만들어주는 특별한 기능, 바로 ‘커스텀 노드(Custom Node)’를 만들고 활용하는 방법에 대해 자세히 알아보겠습니다. 혹시 n8n을 사용하면서 ‘아, 이런 기능이 노드로 있으면 딱인데!’ 하고 생각해보신 적 없으신가요? 바로 그럴 때 커스텀 노드가 빛을 발합니다! ✨
💡 1. 왜 커스텀 노드가 필요할까요?
n8n은 수많은 내장 노드를 제공하여 다양한 서비스와 연동하고 복잡한 워크플로우를 구축할 수 있게 해줍니다. 하지만 다음과 같은 상황에서는 커스텀 노드가 필수적일 수 있습니다.
- 특정 서비스와의 연동 (Proprietary APIs): 여러분이 사용하는 사내 시스템, 특정 산업 분야의 독점적인 API 또는 아직 n8n에서 공식적으로 지원하지 않는 서비스를 연동해야 할 때. 🌐
- 예시: “우리 회사의 오래된 레거시 CRM 시스템 API를 호출해서 데이터를 가져와야 하는데, n8n에 해당 노드가 없네?”
- 복잡한 비즈니스 로직 캡슐화: 여러 내장 노드를 조합해야만 구현 가능한 복잡한 데이터 처리, 변환, 조건 분기 등을 하나의 노드로 묶어 재사용하고 싶을 때. 🧩
- 예시: “CSV 파일을 읽어서 특정 컬럼을 가공하고, 조건에 따라 다른 데이터베이스에 저장하는 일련의 과정을 하나의 노드로 만들어서 재활용하고 싶어!”
- 성능 최적화: JavaScript(TypeScript) 코드를 직접 작성하여 불필요한 네트워크 호출이나 데이터 변환 단계를 줄여 워크플로우의 성능을 향상시키고 싶을 때. ⚡
- 재사용성 및 유지보수성: 반복적으로 사용되는 로직을 노드 형태로 만들어 팀원들과 공유하고, 일관된 방식으로 워크플로우를 구축할 수 있도록 할 때. 🔄
🛠️ 2. 커스텀 노드 개발을 위한 준비물
커스텀 노드를 만들기 위해서는 몇 가지 기본적인 개발 환경 설정이 필요합니다.
- Node.js 및 npm (또는 Yarn): n8n은 Node.js 기반이므로, Node.js와 패키지 매니저(npm 또는 Yarn)가 설치되어 있어야 합니다.
node -v및npm -v또는yarn -v명령어로 설치 여부를 확인할 수 있습니다.
- n8n 설치 (Self-hosted 권장): 개발 및 테스트를 위해 로컬 환경에 n8n이 설치되어 있는 것이 가장 편리합니다. Docker를 이용하는 것이 일반적이지만, Node.js로 직접 설치하는 것도 가능합니다.
npm install n8n -g또는 Dockerdocker run -it --rm --name n8n -p 5678:5678 n8nio/n8n
- TypeScript 지식 (선택 사항이지만 권장): n8n 커스텀 노드는 TypeScript로 개발하는 것을 강력히 권장합니다. 타입 안정성과 개발 생산성을 높여줍니다. JavaScript로도 가능하지만, 이 가이드에서는 TypeScript를 기준으로 설명합니다. 👨💻
- 코드 에디터: VS Code와 같은 코드 에디터를 사용하는 것이 좋습니다.
🧩 3. 커스텀 노드의 구조 이해하기
n8n 커스텀 노드는 기본적으로 다음과 같은 구조를 가집니다.
your-custom-n8n-nodes-project/
├── package.json
└── nodes/
└── YourNodeName/
└── YourNodeName.node.tspackage.json: Node.js 프로젝트의 메타데이터 파일입니다. 여기에 n8n이 커스텀 노드를 인식할 수 있도록n8n필드를 추가해야 합니다.nodes/: 커스텀 노드 파일들이 위치하는 디렉토리입니다.YourNodeName/: 각 커스텀 노드별로 별도의 디렉토리를 생성하는 것이 일반적입니다. (예:GreetingNode/)YourNodeName.node.ts: 실제 노드의 로직이 구현되는 TypeScript 파일입니다. 파일명은[노드이름].node.ts형식을 따라야 합니다.
YourNodeName.node.ts 파일의 핵심 구성 요소:
INodeTypeDescription: 노드의 메타데이터를 정의합니다. UI에 표시되는 이름, 설명, 아이콘, 노드가 받을 수 있는 입력(properties), 노드가 출력할 데이터 형식 등을 설정합니다.name: 노드의 내부적인 고유 이름 (스네이크 케이스, 예:my_custom_node).displayName: n8n UI에 표시될 이름 (예:My Custom Node).icon: 노드 아이콘.description: 노드에 대한 간략한 설명.version: 노드의 버전.group: UI에서 노드가 분류될 그룹 (예:transform,trigger).inputs,outputs: 노드의 입출력 개수.properties: 사용자가 노드에서 설정할 수 있는 필드(입력값)들을 정의합니다.output: 노드가 출력할 데이터의 구조를 정의합니다.
execute()메서드: 노드의 핵심 로직이 실행되는 부분입니다.INodeExecutionData타입의 데이터를 입력으로 받아 처리하고, 새로운INodeExecutionData를 반환합니다.
✍️ 4. 나만의 커스텀 노드 만들기 (예제: 인사말 노드)
간단한 ‘인사말 노드’를 만들어 보겠습니다. 이 노드는 사용자로부터 ‘이름’을 입력받아 “안녕하세요, [이름]님!”이라는 인사말을 출력하는 기능을 합니다.
4.1. 프로젝트 초기 설정 🚀
-
프로젝트 디렉토리 생성:
mkdir custom-n8n-nodes cd custom-n8n-nodes -
npm 프로젝트 초기화:
npm init -y -
n8n 개발 의존성 및 TypeScript 설치:
npm install n8n @n8n/types --save-dev npm install typescript ts-node --save-dev@n8n/types는 n8n 개발에 필요한 타입 정의를 제공합니다.
-
tsconfig.json생성 (TypeScript 설정):npx tsc --inittsconfig.json파일을 열어target을"es2018"또는 그 이상으로,module을"commonjs"로,outDir을./dist로 설정하고,rootDir을./로 설정합니다. 또한allowSyntheticDefaultImports를true로 설정하는 것이 좋습니다.// tsconfig.json { "compilerOptions": { "target": "es2018", "module": "commonjs", "rootDir": "./", "outDir": "./dist", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "allowSyntheticDefaultImports": true }, "include": [ "nodes/**/*.ts" // 노드 파일 포함 ] }
4.2. 노드 파일 생성 📂
-
nodes디렉토리 및 노드별 디렉토리 생성:mkdir nodes mkdir nodes/GreetingNode -
GreetingNode.node.ts파일 생성:touch nodes/GreetingNode/GreetingNode.node.ts
4.3. GreetingNode.node.ts 코드 작성 📝
nodes/GreetingNode/GreetingNode.node.ts 파일을 열고 다음 코드를 붙여넣습니다.
import {
INodeType,
INodeTypeDescription,
INodeProperties,
IExecuteFunctions,
INodeExecutionData,
} from 'n8n-workflow'; // n8n-workflow로 변경됨
export class GreetingNode implements INodeType {
description: INodeTypeDescription = {
displayName: 'Greeting Node 👋', // UI에 표시될 이름
name: 'greetingNode', // 내부적인 고유 이름
icon: 'file:greetingNode.svg', // SVG 아이콘 파일 경로 (옵션)
group: ['transform'], // 노드 그룹 (예: Core, Data, Utility 등)
version: 1, // 노드 버전
description: '입력받은 이름으로 인사말을 생성합니다.', // 노드 설명
defaults: {
name: 'Main', // 기본 워크플로우 이름
},
inputs: ['main'], // 입력 커넥터 (main, additional)
outputs: ['main'], // 출력 커넥터 (main, additional)
properties: [
// 사용자가 노드에서 설정할 수 있는 속성들 (UI 입력 필드)
{
displayName: '이름', // 필드 이름
name: 'userName', // 데이터 접근을 위한 내부 이름
type: 'string', // 데이터 타입 (string, number, boolean, options 등)
default: '', // 기본값
placeholder: '인사할 이름을 입력하세요', // 입력 필드 힌트
description: '인사말을 생성할 대상의 이름을 입력합니다.', // 필드 설명
},
],
};
async execute(this: IExecuteFunctions): Promise {
const items = this.getInputData(); // 입력 데이터 가져오기
const returnData: INodeExecutionData[] = [];
for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
// 'userName' 속성 값 가져오기
// INodeProperties를 통해 정의된 필드는 this.getNodeParameter()로 접근합니다.
const userName = this.getNodeParameter('userName', itemIndex, '') as string;
// 인사말 생성
const greetingMessage = `안녕하세요, ${userName}님! n8n 커스텀 노드를 사용해 주셔서 감사합니다.`;
// 출력 데이터 형식 정의
// 이전 입력 데이터를 유지하고 새로운 데이터를 추가합니다.
// items[itemIndex].json: 입력 데이터의 JSON 본문
// .json 속성에 새로운 데이터를 추가합니다.
// .pairingData 속성을 이용하여 입력과 출력 데이터를 연결할 수 있습니다.
returnData.push({
json: {
greeting: greetingMessage,
originalName: userName, // 원본 이름도 함께 출력
},
// pairingData: { ...items[itemIndex].pairingData }, // 필요시 주석 해제
});
}
// n8n은 항상 2차원 배열을 반환해야 합니다. (각 출력 커넥터별 데이터 배열)
return this.prepareOutputData(returnData);
}
}코드 설명:
import: n8n-workflow 라이브러리에서 필요한 타입들을 가져옵니다.export class GreetingNode implements INodeType:INodeType인터페이스를 구현하는GreetingNode클래스를 정의합니다.description:displayName,name,icon,group,version,description: 노드의 기본적인 정보를 설정합니다.inputs,outputs: 이 노드가 몇 개의 입력과 출력 커넥터를 가질지 정의합니다.['main']은 하나의 'main' 커넥터를 의미합니다.properties: 사용자가 노드 설정 패널에서 입력할 수 있는userName이라는 문자열 필드를 정의합니다.
execute(this: IExecuteFunctions): Promise:- 노드의 핵심 로직이 구현되는 비동기 함수입니다.
this.getInputData(): 이전 노드에서 전달된 모든 입력 데이터를 가져옵니다.this.getNodeParameter('userName', itemIndex, ''):description.properties에 정의된userName필드의 값을 가져옵니다.itemIndex는 현재 처리 중인 데이터 아이템의 인덱스입니다.returnData.push({ json: { greeting: greetingMessage, ... } }): 처리된 데이터를json객체 형태로returnData배열에 추가합니다.this.prepareOutputData(returnData):execute메서드는 항상 이 함수를 통해 2차원 배열 형태의 출력 데이터를 반환해야 합니다.
4.4. package.json 업데이트 📦
package.json 파일을 열어 scripts와 n8n 필드를 추가합니다.
{
"name": "custom-n8n-nodes",
"version": "1.0.0",
"description": "My custom n8n nodes",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"build": "tsc" // TypeScript 컴파일 스크립트 추가
},
"keywords": [],
"author": "",
"license": "MIT",
"devDependencies": {
"@n8n/types": "^1.26.0", // 버전은 현재 n8n 버전에 맞게
"n8n": "^1.26.0", // 버전은 현재 n8n 버전에 맞게
"ts-node": "^10.9.1",
"typescript": "^5.3.3"
},
"n8n": {
"nodes": [
"./nodes/GreetingNode/GreetingNode.node.ts" // 여기에 커스텀 노드 파일 경로를 추가합니다.
]
}
}"n8n"필드: n8n에게 이 프로젝트에 커스텀 노드가 있음을 알려줍니다.nodes배열 안에 커스텀 노드 파일의 상대 경로를 지정합니다.
4.5. 커스텀 노드 테스트하기 ✅
이제 만든 커스텀 노드를 n8n에서 실행해볼 차례입니다.
-
커스텀 노드 빌드:
npm run build이 명령은 TypeScript 파일을 JavaScript로 컴파일하여
dist디렉토리에 생성합니다. n8n은.ts파일도 직접 읽을 수 있으므로 이 단계는 필수는 아니지만, 배포를 고려한다면 좋은 습관입니다. -
n8n 실행 (커스텀 노드 경로 지정):
N8N_ADDITIONAL_MODULES_PATH환경 변수를 사용하여 n8n에게 커스텀 노드가 있는 디렉토리를 알려줍니다. 현재 디렉토리에서 실행하는 경우.:N8N_ADDITIONAL_MODULES_PATH=$(pwd) n8n start$(pwd)는 현재 작업 디렉토리의 절대 경로를 반환합니다. Windows PowerShell에서는$(Get-Location)를 사용하거나 직접 경로를 입력해야 할 수 있습니다. (예:set N8N_ADDITIONAL_MODULES_PATH=C:\Users\YourUser\custom-n8n-nodes&n8n start)- Docker를 사용하는 경우,
-v옵션으로 커스텀 노드 디렉토리를 마운트하고N8N_ADDITIONAL_MODULES_PATH환경 변수를 Docker 컨테이너 내의 경로로 설정합니다.docker run -it --rm \ -p 5678:5678 \ -v $(pwd):/home/node/custom-nodes \ -e N8N_ADDITIONAL_MODULES_PATH=/home/node/custom-nodes \ n8nio/n8n
-
n8n UI에서 테스트:
-
웹 브라우저에서
http://localhost:5678로 n8n UI에 접속합니다. -
새로운 워크플로우를 생성합니다.
-
노드 추가(+) 버튼을 누르고 검색창에
Greeting또는Greeting Node를 입력하면 방금 만든 노드가 나타날 것입니다. 🎉 -
워크플로우 예시:
Start노드를 추가합니다.Greeting Node를 추가하고Start노드에 연결합니다.Greeting Node의 설정 패널에서 ‘이름’ 필드에 “자동화 마법사”라고 입력합니다.Set노드를 추가하여 이전 노드의 데이터를 확인하거나,Respond to Webhook또는Log노드를 추가하여 최종 출력을 확인합니다.- 워크플로우를 실행(Execute Workflow)하여 결과를 확인합니다.
-
예상 결과:
Greeting Node의 출력 데이터에json.greeting: "안녕하세요, 자동화 마법사님! n8n 커스텀 노드를 사용해 주셔서 감사합니다."와 같은 메시지가 포함되어 있을 것입니다.
-
🚀 5. 고급 고려 사항
- 인증 정보 (Credentials): API 키와 같은 민감한 정보는
properties로 직접 입력받기보다credentials를 사용하는 것이 안전합니다. 이는 n8n이 암호화하여 관리하며, 워크플로우를 공유할 때 인증 정보가 노출되지 않도록 합니다.credentials를 사용하려면description에credentials필드를 추가하고, 별도의CredentialType.ts파일을 생성해야 합니다.
-
에러 처리:
NodeOperationError를 사용하여 노드 실행 중 발생하는 에러를 n8n이 인식하고 처리할 수 있도록 합니다.import { NodeOperationError } from 'n8n-workflow'; // ... execute 함수 내에서 if (!userName) { throw new NodeOperationError('이름을 입력해야 합니다.', { itemIndex }); } - 다중 입력/출력 (Multiple Inputs/Outputs):
inputs: ['main', 'alt'],outputs: ['success', 'failure']와 같이 여러 개의 입출력 커넥터를 가질 수 있습니다.getInputData(0)또는getInputData(1)처럼 인덱스로 특정 커넥터의 데이터를 가져올 수 있습니다. - 데이터 타입:
properties에서 다양한 데이터 타입을 사용할 수 있습니다.string,number,boolean,options,multiOptions,fixedCollection,json,resourceAll등. - 테스트 및 디버깅:
console.log()를 사용하여 데이터를 출력하거나, VS Code의 디버거를 n8n 프로세스에 연결하여 스텝별로 디버깅할 수 있습니다.
🎉 6. 결론
n8n 커스텀 노드는 여러분의 자동화 가능성을 무한대로 확장시켜주는 강력한 도구입니다. 특정 서비스와의 연동부터 복잡한 비즈니스 로직 캡슐화까지, 커스텀 노드를 통해 워크플로우를 더욱 강력하고 유연하게 만들 수 있습니다. 처음에는 조금 복잡하게 느껴질 수 있지만, 이 가이드를 따라 차근차근 진행하다 보면 여러분만의 독창적인 자동화 블록을 만들어내는 재미에 푹 빠지실 겁니다.
이제 여러분의 상상력을 발휘하여 n8n으로 어떤 멋진 자동화를 만들어낼지 기대가 됩니다! 🚀 궁금한 점이 있다면 언제든지 질문해주세요. 행복한 자동화 생활 되세요! 😊 D