Node.js, JavaScript'i tarayıcının dışında, yani sunucuda, terminalde ya da kendi bilgisayarınızda çalıştırmanızı sağlayan bir runtime. Node js nedir diye arayan çoğu kişi aslında şunu soruyor: frontend'de kullandığım JavaScript'le backend de yazabilir miyim? Evet, Node.js tam olarak bunun için var.

Bugün backend servislerini Node.js, NestJS ve TypeScript ile, PostgreSQL üzerinde yazıyorum. Bu yazıda Node.js'in ne olduğunu, event loop'un nasıl çalıştığını, npm'i ve sıfırdan küçük bir HTTP sunucusunu anlatıyorum. Sonunda da Node.js'in hangi işlere uyup hangilerine uymadığına bakıyoruz.

Node.js nedir, ne işe yarar?

JavaScript uzun yıllar yalnızca tarayıcıda çalışan bir dildi. Node.js, 2009'da Ryan Dahl tarafından, Chrome'un JavaScript motoru V8'in üzerine kuruldu. V8 JavaScript kodunu çalıştırıyor, Node.js de ona tarayıcıda olmayan yetenekleri ekliyor: dosya okuyup yazmak, ağ bağlantısı açmak, HTTP sunucusu kurmak, işletim sistemi süreçleriyle konuşmak.

Node.js ile yapılan yaygın işler:

  • REST ve GraphQL API'leri, yani bir uygulamanın backend'i
  • WebSocket ile gerçek zamanlı uygulamalar (sohbet, canlı bildirim, ortak düzenleme)
  • Komut satırı araçları (npx ile çalıştırdığınız paketler Node.js üzerinde çalışıyor)
  • Vite, webpack gibi frontend build araçları
  • Electron ile masaüstü uygulamaları

API kavramına yabancıysanız önce API nedir yazısına bakmanızı öneririm, Node.js ile yazılan şeylerin çoğu bir API.

Node.js bir programlama dili mi?

Hayır. Dil JavaScript, Node.js onu çalıştıran ortam. Tarayıcıdaki JavaScript ile Node.js'deki JavaScript aynı dil, ama erişebildikleri şeyler farklı. Tarayıcıda document ve window var, dosya sistemine erişim yok. Node.js'de document yok, ama fs modülüyle dosya okuyabiliyor, http modülüyle sunucu açabiliyorsunuz.

Node.js bir framework de değil. Express ve NestJS framework, Node.js'in üzerinde çalışıyorlar.

Event loop nedir? Sade bir anlatım

Node.js'i diğer backend ortamlarından ayıran şey çalışma modeli. JavaScript kodunuz tek bir thread'de çalışıyor. İlk duyduğunuzda bu bir dezavantaj gibi geliyor: tek thread nasıl binlerce isteğe cevap verecek?

Cevap, beklemenin nasıl yapıldığında. Bir web sunucusunun zamanının büyük kısmı hesap yapmakla değil beklemekle geçiyor: veritabanından cevap beklemek, diskten dosya okumak, başka bir API'yi çağırmak. Node.js bu bekleme işlerini işletim sistemine ya da arka plandaki bir thread havuzuna (libuv) devrediyor ve beklerken başka işlere bakıyor. İş bittiğinde, o işe verdiğiniz callback bir kuyruğa giriyor. Event loop da bu kuyruğu sürekli dönen, sırası gelen callback'i çalıştıran döngü.

Bir restorandaki garson gibi düşünün. Garson siparişi alıyor, mutfağa iletiyor ve yemek pişene kadar mutfağın önünde beklemiyor. Diğer masalara bakıyor. Yemek hazır olunca alıp masaya götürüyor. Tek bir garson bu şekilde birçok masaya yetişebiliyor.

Bunu kodda görmek için:

const fs = require("node:fs");

console.log("1. başladı");

fs.readFile(__filename, () => {
  console.log("3. dosya okundu");
});

setTimeout(() => {
  console.log("4. zamanlayıcı bitti");
}, 100);

console.log("2. bitti, ama işler hâlâ sürüyor");

Çıktı:

1. başladı
2. bitti, ama işler hâlâ sürüyor
3. dosya okundu
4. zamanlayıcı bitti

Dosya okuma ve zamanlayıcı başlatıldı ama kod onları beklemeden devam etti. İkisi bittiğinde callback'leri sırayla çalıştı. Bugün çoğu kodu callback yerine async/await ile yazıyoruz, ama alttaki mekanizma aynı.

Bu modelin bir sınırı var: event loop'u kendi kodunuz meşgul ederse her şey duruyor. Büyük bir dosyayı senkron sıkıştırmak ya da milyonlarca elemanlı bir diziyi tek seferde sıralamak gibi ağır CPU işleri, o iş bitene kadar diğer isteklerin cevaplanmasını engelliyor. Böyle işler için worker_threads modülü ya da işi ayrı bir servise taşımak gerekiyor.

Node.js nasıl kurulur?

En kolayı nodejs.org adresinden LTS sürümünü indirmek. LTS (Long Term Support) uzun süre güvenlik güncellemesi alan sürüm ve production için Node.js'in kendi önerisi de bu. Şu anda LTS olan sürümler 26 (Lithium), 24 (Krypton) ve 22 (Jod). Node.js 27 ile birlikte takvim değişiyor: her yıl bir ana sürüm çıkacak ve her biri LTS olacak.

Birden fazla projeyle çalışıyorsanız nvm ya da fnm gibi bir sürüm yöneticisi kullanmak daha rahat. Projeler arasında Node sürümünü tek komutla değiştirebiliyorsunuz.

Kurulumdan sonra:

node -v
npm -v

npm nedir?

npm, Node.js ile birlikte gelen paket yöneticisi. Başkalarının yazdığı kütüphaneleri projenize eklemenizi, kendi kütüphanelerinizi de yayınlamanızı sağlıyor.

Yeni bir proje başlatmak:

mkdir benim-api && cd benim-api
npm init -y

Bu komut bir package.json oluşturuyor. Projenin adı, sürümü, bağımlılıkları ve script'leri bu dosyada duruyor. Bir paket kurduğunuzda:

npm install express

paket node_modules klasörüne iniyor, package.json içindeki dependencies listesine ekleniyor ve kurulan tam sürümler package-lock.json dosyasına yazılıyor. node_modules klasörünü git'e eklemiyorsunuz, package-lock.json dosyasını ekliyorsunuz. Başka biri projeyi klonladığında npm ci ile aynı sürümleri kuruyor.

Sık kullandığım komutlar:

npm install            # package.json'daki her şeyi kur
npm install -D vitest  # sadece geliştirmede gereken bir paket
npm run dev            # package.json'daki "dev" script'ini çalıştır
npx random-memes       # bir paketi kurmadan tek seferlik çalıştır

Node.js ile basit bir HTTP sunucusu

Hiçbir paket kurmadan, yalnızca Node.js'in kendi http modülüyle bir sunucu:

const http = require("node:http");

const server = http.createServer((req, res) => {
  if (req.method === "GET" && req.url === "/merhaba") {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ mesaj: "Merhaba, Node.js!" }));
    return;
  }

  res.writeHead(404, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ hata: "Bulunamadı" }));
});

server.listen(3000, () => {
  console.log("Sunucu http://localhost:3000 adresinde çalışıyor");
});

server.js olarak kaydedip çalıştırın, başka bir terminalden de isteği atın:

node server.js
curl -i http://localhost:3000/merhaba
HTTP/1.1 200 OK
Content-Type: application/json

{"mesaj":"Merhaba, Node.js!"}

Küçük bir iş için bu yetiyor. Ama route sayısı arttıkça if blokları büyüyor, gövdeyi okumak, hataları yakalamak, middleware eklemek elle yapılınca yoruyor. Burada framework'ler devreye giriyor. Aynı endpoint Express ile:

const express = require("express");

const app = express();

app.get("/merhaba", (req, res) => {
  res.json({ mesaj: "Merhaba, Express!" });
});

app.listen(3000);

Express küçük ve esnek. Proje büyüdükçe klasör yapısını, doğrulamayı, bağımlılıkları nasıl yöneteceğinize siz karar veriyorsunuz. NestJS ise bu kararların çoğunu sizin yerinize veriyor: modüller, controller'lar, servisler, dependency injection ve decorator'larla TypeScript üzerine kurulu bir yapı. Şu anki işimde backend servislerini NestJS ile yazıyorum. Birden fazla kişinin aynı kod tabanında çalıştığı projelerde bu yapı işleri kolaylaştırıyor. NestJS için yazdığım nest-cloudflare-turnstile kütüphanesi de Cloudflare Turnstile captcha doğrulamasını bir guard ve bir decorator olarak ekliyor.

Express uygulamasını sunucusuz bir ortamda çalıştırmak isterseniz Express uygulamasını Vercel'e deploy etmek üzerine bir yazım da var.

Node.js'i TypeScript ile kullanmak

Büyük bir Node.js projesinde JavaScript'in tip kontrolü olmaması zamanla can sıkıyor. İş yerinde yazdığım Node.js servisleri bu yüzden TypeScript ile. Güncel Node.js sürümleri (22.18 ve 23.6'dan itibaren) yalnızca tip açıklaması içeren .ts dosyalarını ek bir araç olmadan çalıştırabiliyor:

node server.ts

Node.js burada tipleri silip kodu çalıştırıyor, tip kontrolü yapmıyor. enum gibi JavaScript'e çevrilmesi gereken özellikleri de desteklemiyor. Tip kontrolü için yine tsc gerekiyor. Detaylar TypeScript nedir yazısında.

Node.js nerede kullanılır, nerede kullanılmaz?

Node.js her backend sorununun cevabı değil. Benim gördüğüm tablo şu:

İşNode.js uygun mu?
REST/GraphQL API, çok sayıda kısa istekÇok uygun
WebSocket, gerçek zamanlı uygulamaÇok uygun
Frontend ile aynı dili paylaşan full stack ekipÇok uygun
CLI araçları, script'lerUygun
Video işleme, ağır hesaplama, makine öğrenmesiGenelde başka bir dil daha iyi

Go, Java, C# ya da Python ile de aynı API'yi yazabilirsiniz. Node.js'in asıl avantajı dilden çok ekosistem ve ekip: frontend'de JavaScript ya da TypeScript yazan bir ekip, backend'e geçerken yeni bir dil öğrenmek zorunda kalmıyor, tipleri ve doğrulama kodunu iki taraf arasında paylaşabiliyor. Ağır hesaplama gereken bir iş varsa onu ayrı bir servise koyup Node.js ile konuşturmak da yaygın bir yöntem.

Backend'in genel olarak ne olduğunu ve hangi parçalardan oluştuğunu Backend nedir yazısında anlattım.

Benim yazdığım Node.js kütüphaneleri

npm'e yayınladığım birkaç küçük Node.js kütüphanesi var. Hepsi açık kaynak ve MIT lisanslı:

  • logmoji: her satırı bir emoji, log seviyesi, renk ve zaman damgasıyla yazan küçük bir logger.
  • random-memes: Lemmy topluluklarından rastgele meme getiren bir kütüphane ve CLI. Bağımlılığı yok, Node.js'in kendi fetch'ini kullanıyor, Node.js 20 veya üstü istiyor.
  • shotsnap: bir URL'in ekran görüntüsünü bulutta çalışan bir tarayıcı üzerinden alıp PNG olarak Buffer döndüren bir kütüphane. Puppeteer ya da Chrome kurmanız gerekmiyor.
  • temp-mail-plus-api: Temp Mail Plus için resmi olmayan bir Node.js ve TypeScript istemcisi. Geçici e-posta adresi oluşturup gelen kutusunu okuyor.

Küçük bir kütüphane yazıp npm'e yayınlamak Node.js'i öğrenmenin iyi bir yolu. package.json, modül sistemi, sürümleme ve başkalarının kodunuzu nasıl kullandığı konusunda tek bir projeden çok şey öğreniyorsunuz.

Sık sorulan sorular

Node.js frontend mi backend mi?

Node.js backend tarafında çalışıyor. Frontend projelerinde de build araçlarını çalıştırmak için kullanılıyor, ama kullanıcının tarayıcısında çalışan kod Node.js değil.

Node.js öğrenmek için önce JavaScript bilmek gerekir mi?

Evet. Değişkenler, fonksiyonlar, nesneler, Promise ve async/await konularını bilmeden Node.js'e geçmek işleri zorlaştırıyor. Özellikle asenkron kodu anlamadan event loop'u anlamak zor.

Hangi Node.js sürümünü kullanmalıyım?

Production için güncel LTS sürümlerinden birini. Bugün bunlar 26, 24 ve 22. Yeni bir projeye başlıyorsanız en yeni LTS ile başlayın.

Node.js mi, Express mi, NestJS mi?

Bunlar birbirinin alternatifi değil. Express ve NestJS, Node.js üzerinde çalışan framework'ler. Küçük bir API için Express yetiyor, büyük ve çok kişili bir proje için NestJS'in yapısı işinizi kolaylaştırıyor.

Node.js ile yazılmış bir projeyi nasıl deploy ederim?

En yaygın yol uygulamayı bir container image'ına koyup sunucuda çalıştırmak. Nasıl yapıldığını Docker nedir yazısında bir Dockerfile örneğiyle anlattım. Projeniz için bir backend geliştiriciye ihtiyacınız varsa freelance çalıştığım işlere bakabilirsiniz.