Belajar n8n - Extensions & Custom Nodes

#Pendahuluan

Di episode 16 kalian mengoptimalkan performa workflow dengan sub-workflow, batch, dan scaling. Tapi ada batas yang tidak bisa ditembus optimasi: API internal perusahaan yang tidak punya node bawaan. Memanggilnya dengan HTTP Request berulang kali di banyak workflow itu melelahkan, rawan salah, dan sulit dipelihara. Di titik inilah n8n menunjukkan keunggulan open-source-nya — kalian bisa membangun node sendiri.

#Kapan Membutuhkan Custom Node

Custom node bukan jawaban untuk semua integrasi. Aturan praktisnya: menyalin konfigurasi HTTP Request yang sama tiga kali atau lebih adalah sinyal kuat untuk menulis node. Pertimbangkan dulu:

• Satu atau dua panggilan ke sebuah API → cukup HTTP Request dengan credential Header Auth.
• Panggilan berulang di banyak workflow → custom node menghemat duplikasi dan menyembunyikan detail autentikasi.
• Logika pemanggilan kompleks — pagination, retry, penanganan error spesifik API → custom node membungkusnya sekali untuk semua pemakai.
• Berbagi dengan tim/komunitas → paket node bisa di-publish ke npm.

#Menggunakan Community Nodes

Sebelum menulis dari nol, cek community nodes — node yang dibuat komunitas dan diinstal langsung dari UI melalui Settings → Community Nodes. Node ini bisa dipasang dengan memilih nama paket, lalu muncul di panel node seperti node bawaan.

Kepercayaan perlu dijaga: node yang sudah verified oleh n8n memenuhi standar teknis dan UX, sedangkan node tidak terverifikasi perlu ditelusuri kode sumbernya dulu. Untuk self-hosted, pastikan instalasi community nodes diaktifkan pada main dan worker:

N8N_COMMUNITY_NODES_ENABLED=true

#Scaffolding Proyek Custom Node

Cara resmi memulai adalah scaffolding CLI. Perintah npm create @n8n/node@latest menghasilkan proyek lengkap dengan struktur node, credential, linter, dan tooling build:

npm create @n8n/node@latest my-api-node
cd my-api-node
npm run dev

npm run dev menjalankan n8n-node dev: mem-build node, menyalakan n8n di http://localhost:5678, menghubungkan node ke folder custom, dan me-rebuild otomatis setiap file berubah. Kalian langsung menguji node di editor nyata tanpa publish ke mana-mana.

#Anatomi Custom Node

Sebuah node adalah kelas TypeScript yang mengimplementasikan antarmuka INodeType, berisi dua bagian: description (metadata dan form UI) dan execute (logika eksekusi). Contoh node sederhana yang mengambil satu task dari sebuah API:

import {
	IExecuteFunctions,
	INodeExecutionData,
	INodeType,
	INodeTypeDescription,
} from 'n8n-workflow';
 
export class MyApi implements INodeType {
	description: INodeTypeDescription = {
		displayName: 'MyApi',
		name: 'myApi',
		icon: 'file:myApi.svg',
		group: ['transform'],
		version: 1,
		description: 'Ambil data task dari API internal',
		defaults: { name: 'MyApi' },
		inputs: ['main'],
		outputs: ['main'],
		credentials: [{ name: 'myApiCredentials', required: true }],
		properties: [
			{
				displayName: 'Task ID',
				name: 'taskId',
				type: 'string',
				default: '',
				description: 'ID task yang ingin diambil',
			},
		],
	};
 
	async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
		const items = this.getInputData();
		const returnData: INodeExecutionData[] = [];
 
		for (let i = 0; i < items.length; i++) {
			const taskId = this.getNodeParameter('taskId', i) as string;
			const credentials = await this.getCredentials('myApiCredentials');
			const response = await this.helpers.httpRequest({
				method: 'GET',
				url: `${credentials.baseUrl}/v1/tasks/${taskId}`,
				headers: { Authorization: `Bearer ${credentials.apiKey}` },
				json: true,
			});
			returnData.push({ json: response });
		}
		return [returnData];
	}
}

Perhatikan pola pentingnya: kredensial diambil lewat getCredentials sehingga nilai rahasia tidak pernah tertanam di parameter node — persis prinsip keamanan episode 12. helpers.httpRequest dipilih daripada fetch mentah karena mengikuti pengaturan proxy dan retry n8n. Nama credential di credentials harus cocok persis dengan nama kelas credential-nya.

#Credential Custom

Node kalian membutuhkan tipe credential sendiri. Kelas credential mengimplementasikan ICredentialType dan mendefinisikan field yang ditampilkan saat user mengisi:

import { ICredentialType, INodeProperties } from 'n8n-workflow';
 
export class MyApiCredentials implements ICredentialType {
	name = 'myApiCredentials';
	displayName = 'MyApi Credentials';
	properties: INodeProperties[] = [
		{
			displayName: 'Base URL',
			name: 'baseUrl',
			type: 'string',
			default: 'https://api.internal.example.com',
		},
		{
			displayName: 'API Key',
			name: 'apiKey',
			type: 'string',
			typeOptions: { password: true },
			default: '',
		},
	];
}

Field dengan typeOptions: { password: true } dirender sebagai input password dan tidak akan muncul dalam teks polos — menjaga rahasia tetap tersembunyi di UI.

#Mengemas, Menguji & Men-deploy

Agar n8n mengenali paket kalian, package.json harus mendaftarkan node dan credential di bawah kunci n8n, dan nama paket wajib diawali n8n-nodes-:

{
  "name": "n8n-nodes-my-api",
  "version": "0.1.0",
  "n8n": {
    "n8nNodesApiVersion": 1,
    "nodes": ["dist/nodes/MyApi/MyApi.node.js"],
    "credentials": ["dist/credentials/MyApiCredentials.credentials.js"]
  },
  "main": "index.js"
}

Uji lokal dengan npm run build lalu npm link ke folder custom, atau terus gunakan npm run dev yang sudah menangani semuanya. Untuk distribusi:

npm run build
npm run lint
npm publish

Pemakai lain kemudian menginstalnya dari registry dengan npm install n8n-nodes-my-api atau dari UI Community Nodes. Untuk self-hosted berbasis Docker, node juga bisa dipasang saat membangun image:

FROM docker.n8n.io/n8nio/n8n:latest
USER root
RUN cd /usr/local/lib/node_modules/n8n \
    && npm install n8n-nodes-my-api
USER node

Setelah node dirilis dan dipakai, pertahankan kompatibilitas: jangan mengubah nilai name node setelah dipublish, karena workflow yang sudah tersimpan mereferensikannya. Perubahan perilaku ditangani dengan menaikkan version pada deskripsi node — bukan mengganti nama.

#Penutup

Inti yang harus dibawa pulang:

• Custom node untuk integrasi berulang, HTTP Request untuk panggilan sesekali.
• Community nodes mempercepat tanpa menulis kode — pilih yang sudah verified.
• Node adalah INodeType dengan description untuk UI dan execute untuk logika.
• Credential custom memakai ICredentialType dengan field password yang tersembunyi.
• Nama paket wajib n8n-nodes- dan didaftarkan di kunci n8n pada package.json.

Di episode 18 berikutnya kita menutup siklus hidup pengembangan: CI/CD & Workflow Lifecycle — versioning definisi workflow dengan Git, continuous deployment untuk perubahan workflow, serta testing dan validasi sebelum naik ke produksi. Sampai jumpa!