"환경이 갖춰지면 절반은 이미 완성된 것이다."
— 도널드 크누스 (Donald Knuth, 컴퓨터 과학자)🎯 오늘의 학습 목표- 커스텀 노드 개발에 필요한 환경을 로컬 PC에 구성할 수 있다.
- n8n-nodes-starter 템플릿 구조를 이해할 수 있다.
- 로컬 n8n에서 커스텀 노드를 빌드하고 동작을 확인할 수 있다.
커스텀 노드란?커스텀 노드(Custom Node)는 n8n에 없는 외부 서비스나 특수한 처리 로직을 직접 노드로 만드는 기술입니다. 회사 전용 ERP 연동, 국내 SMS 서비스 연동, 복잡한 데이터 변환 등 기본 노드로 해결할 수 없는 상황에서 사용합니다.
Step 1 — 개발 환경 준비 (내 PC에서)
bash
node --version # 18 이상 필요
npm --version
💡 Node.js가 없다면 https://nodejs.org 에서 LTS 버전을 설치하세요.
Step 2 — n8n 공식 스타터 템플릿으로 프로젝트 생성
bash
git clone https://github.com/n8n-io/n8n-nodes-starter.git my-custom-nodes
cd my-custom-nodes
npm install
생성된 폴더 구조
text
my-custom-nodes/
├── nodes/
│ └── ExampleNode/
│ ├── ExampleNode.node.ts ← 핵심: 노드 로직
│ └── ExampleNode.svg ← 노드 아이콘
├── credentials/
│ └── ExampleCredentials.credentials.ts
├── package.json
└── tsconfig.json
Step 3 — 빌드 및 로컬 n8n에서 테스트
bash
# TypeScript 빌드
npm run build
# 로컬 n8n 실행 (서버가 아닌 로컬)
npx n8n start
로컬 테스트 확인브라우저에서 http://localhost:5678 으로 접속하면 커스텀 노드가 노드 패널에 나타납니다.
🛠️ DAY 22 실습Step 1Node.js 설치 및 버전 확인
- node --version 으로 18 이상인지 확인
- 버전이 낮다면 https://nodejs.org 에서 LTS 설치
- npm --version 으로 npm도 정상 동작 확인
Step 2스타터 템플릿 클론 및 설치
- git clone https://github.com/n8n-io/n8n-nodes-starter.git my-custom-nodes
- cd my-custom-nodes && npm install
- 생성된 폴더 구조를 VS Code 등으로 열어서 확인
Step 3빌드 및 동작 확인
- npm run build 로 TypeScript 컴파일
- npx n8n start 로 로컬 n8n 실행
- http://localhost:5678 접속 후 노드 패널에서 'ExampleNode' 확인
🚀 DAY 22 미션개발 환경을 완성하고, ExampleNode가 로컬 n8n 노드 패널에 표시되는 것을 캡처해두세요. 이게 DAY 23~24 커스텀 노드 개발의 출발점입니다.
☑️ 미션 체크리스트- Node.js 18+ 설치 완료
- n8n-nodes-starter 클론 및 npm install 완료
- npm run build 성공 (오류 없음)
- 로컬 n8n에서 ExampleNode 확인
💡 힌트: npm run build에서 TypeScript 오류가 나면 tsconfig.json의 target을 es2019로 변경해보세요.
🎯 성공 기준: http://localhost:5678 의 노드 패널에서 ExampleNode가 보이는 상태