n8n’de Kendi Custom Node’unu Yazmak: Gerçekten Çalışan Yol

Bu yazıda, n8n içinde kendi custom node’unu sıfırdan nasıl oluşturacağını adım adım öğreneceksin. Sadece “nasıl yapılır” değil, neden yapılır, hangi durumlarda mantıklıdır ve en önemlisi gerçek hayatta çalışan setup nasıl kurulur bunu göreceksin.

Şimdi şöyle bir düşün: n8n kullanıyorsun ama ihtiyacın olan şey için ne hazır node var ne de community node. İşte tam burada kendi node’unu yazmak devreye giriyor.

---

n8n’de Custom Node Yazmak Ne Zaman Mantıklı?

Aslında bu çok basit: Eğer ihtiyacın olan şey hazır değilse 3 seçeneğin var:

• HTTP Request Node
• Code Node (JavaScript / Python)
• Custom Node yazmak

Burada kritik fark şu:

Custom node yazdığında, ortaya çıkan şey artık sadece senin için değil, başkalarının da kolayca kullanabileceği bir “ürün” haline geliyor.

Yani şöyle düşün:

Tek seferlik script yazmak yerine, bir “buton” yapıyorsun. Başkası sadece tıklayıp kullanıyor.

---

Declarative vs Programmatic Node

n8n’de iki tip custom node var:

• Declarative
• Programmatic

Bu yazıda kullanılan yaklaşım: Declarative

Neden?

Çünkü çoğu senaryo için yeterli ve daha sürdürülebilir.

Yani şöyle düşün:

Declarative = yapılandırma bazlı (JSON + tanım)

Programmatic = tamamen kodla kontrol

---

Projeyi Başlatmak (Starter Template)

Başlangıç noktası:

👉 n8n-io/n8n-nodes-starter

Projeyi indiriyorsun ve klasörü şu şekilde düzenliyorsun:

nodes/
credentials/

Örnek dosyaları siliyorsun ve sıfırdan başlıyorsun.

Son yapı:

nodes/cityweather/
  ├── cityweather.node.ts
  ├── cityweather.node.json
  ├── openweather.svg

credentials/
  └── cityweatherapi.credentials.ts

---

Node Yapısı: cityweather.node.ts

İlk olarak import ve class yapısı:

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

export class CityWeather implements INodeType {
  description: INodeTypeDescription = {
    // ...
  };
}

Bu dosya node’un “beyni”.

Yani şöyle düşün:

Bu dosya, node’un ne yaptığı ve nasıl davrandığı.

---

Node Detayları ve API Bağlantısı

Burada OpenWeatherMap API kullanılıyor.

Base URL:

<https://api.openweathermap.org/data/2.5/weather>

Node içinde bu API’ye bağlanacak şekilde tanımlama yapılıyor.

---

UI (Kullanıcı Arayüzü) Tanımı

Node’un en kritik kısmı: kullanıcıdan ne alıyorsun?

Zorunlu alan:

• city

Opsiyonel alanlar:

• format (imperial, metric, scientific)
• language

Kod mantığı şu:

{
  displayName: 'City',
  name: 'city',
  type: 'string',
  required: true,
}

{
  displayName: 'Format',
  name: 'format',
  type: 'options',
  options: [
    { name: 'Metric', value: 'metric' },
    { name: 'Imperial', value: 'imperial' },
    { name: 'Scientific', value: 'standard' }
  ],
  default: 'metric'
}

Yani şöyle düşün:

Kullanıcıya sadece gerekli kontrolleri gösteriyorsun. Gereksiz karmaşıklığı saklıyorsun.

---

Credentials (API Key Yönetimi)

Dosya:

cityweatherapi.credentials.ts

Burada kritik detay:

OpenWeatherMap API key parametresi:

appid

Kod:

{
  name: 'appid',
  type: 'string',
  default: '',
}

Yani şöyle düşün:

API key’i kod içine gömmek yerine kullanıcıdan alıyorsun. Güvenli ve reusable oluyor.

---

Node Metadata (JSON Dosyası)

Dosya:

cityweather.node.json

Bu dosya node’un n8n içinde nasıl görüneceğini belirler.

Örnek:

{
  "name": "cityWeather",
  "displayName": "City Weather",
  "description": "Get weather by city"
}

---

Büyük Tuzak: PNPM vs NPM Sorunu

Burada çoğu kişinin takıldığı kritik konu var.

n8n, 2024 Temmuz’dan sonra:

👉 pnpm kullanmaya başladı

Ama eski tutorial’lar:

👉 npm üzerinden gidiyor

Sonuç?

👉 Çalışmıyor.

Çözüm:

👉 Eski package.json (Mayıs 2024 versiyonu) kullanmak

Yani şöyle düşün:

Yanlış araçla doğru işi yapmaya çalışıyorsun → sistem çöküyor.

---

Build ve Kurulum

Proje klasöründe:

npm install
npm run build
npm link

Sonra n8n dizininde:

cd ~/.n8n
mkdir custom
cd custom
npm init

Ve node’u bağla:

npm link n8n-nodes-cityweather

---

n8n İçinde Kullanım

n8n’i başlat:

n8n

Node’u arat:

👉 City Weather

Artık input verebilirsin:

• city: Denmark
• format: metric

Output:

• sıcaklık
• şehir bilgisi
• hava durumu

---

Query String Mantığı

Node içinde API çağrısı şu şekilde kurulur:

qs: {
  q: city,
  units: format,
  lang: language
}

Yani şöyle düşün:

Form dolduruyorsun → URL’e parametre olarak ekleniyor.

---

Değişiklik Yapmak ve Güncellemek

Her değişiklikten sonra:

npm run build
npm link n8n-nodes-cityweather

n8n’i restart et → değişiklik gelir.

---

Gerçek Hayat Avantajı

Custom node yazmanın en büyük gücü:

👉 Kullanıcıyı kısıtlarsın

Örnek:

Normal OpenWeatherMap node → çok fazla parametre

Custom node → sadece city

Yani şöyle düşün:

Kullanıcıya cockpit değil, sadece direksiyon veriyorsun.

---

n8n Source Code’dan Öğrenmek

n8n tüm node’larını GitHub’da açık tutuyor.

Özellikle:

👉 OpenWeatherMap node

Buradan şunları öğrenebilirsin:

• UI nasıl kuruluyor
• API nasıl bağlanıyor
• advanced kullanım nasıl

---

Özet

Custom node yazmak ilk başta karmaşık görünüyor ama aslında yapı net:

bir template alıyorsun, UI’ı tanımlıyorsun, API bağlantısını kuruyorsun ve n8n’e bağlıyorsun. En kritik nokta ise tooling uyumsuzluğu; pnpm yerine npm kullanarak sistemi gerçekten çalışır hale getiriyorsun. Sonuçta ortaya çıkan şey sadece bir entegrasyon değil, tekrar tekrar kullanılabilen, sadeleştirilmiş bir arayüz oluyor.

---

Bu yazı “Create your own Custom Node” videosundan ilham alınarak yazılmıştır.

---

Kaynakça:

• https://www.youtube.com/watch?v=nX_8OVhUVSY