NPM CORS paketi

npm’deki cors paketi, Express uygulamanızın farklı origin’lerden gelen tarayıcı isteklerine hangi koşullarda izin vereceğini HTTP yanıt başlıklarıyla belirler. CORS, API’yi herkese açan bir güvenlik sistemi değildir; yalnızca tarayıcının yanıtı istemci JavaScript’ine verip vermeyeceğini kontrol eder. API yetkilendirmesi ayrıca yapılmalıdır.

En küçük çalışan Express örneği​

Ön koşul olarak Node.js yüklü boş bir klasör kullanın. Aşağıdaki örnek yalnızca http://localhost:5173 origin’inden gelen tarayıcı isteklerine izin verir.

1. Yeni proje oluşturup bağımlılıkları yükleyin:
   
   Kod:

   mkdir cors-ornek
   cd cors-ornek
   npm init -y
   npm install express cors

2. Klasörde server.js adlı dosya oluşturup şu kodu yerleştirin:
   
   Kod:

   const express = require('express');
   const cors = require('cors');
   
   const app = express();
   const PORT = 3000;
   
   app.use(cors({
     origin: 'http://localhost:5173'
   }));
   
   app.get('/api/mesaj', (req, res) => {
     res.json({ mesaj: 'CORS ayarı çalışıyor' });
   });
   
   app.listen(PORT, '127.0.0.1', () => {
     console.log(`API http://127.0.0.1:${PORT} adresinde çalışıyor`);
   });

3. Sunucuyu çalıştırın (bu yeni örnek CommonJS kullanır; mevcut type: module projesine require kodunu aynen taşımayın):
   
   Kod:

   node server.js

4. Başka bir terminalde origin başlığını taklit ederek yanıtı kontrol edin:
   
   Kod:

   curl -i -H "Origin: http://localhost:5173" http://127.0.0.1:3000/api/mesaj

Tarayıcı denemesi için ön yüzünüzü gerçekten http://localhost:5173 origin’i üzerinde sunun. Başka bir port veya 127.0.0.1 kullanıyorsanız izinli origin’i buna göre değiştirin; curl komutu ön yüz sunucusu oluşturmaz. Üretimde hem API hem ön yüz için uygun HTTPS kullanın.

Başarılı yanıtta Access-Control-Allow-Origin: http://localhost:5173 başlığını ve {"mesaj":"CORS ayarı çalışıyor"} içeriğini görürsünüz. Bu başlık yoksa veya farklı origin gönderirseniz, istek sunucuya ulaşsa bile tarayıcı yanıtı JavaScript koduna kullandırmaz.

Ayarı nasıl seçmelisiniz?​

origin seçeneği, hangi web uygulamasının API yanıtını okuyabileceğini belirler. Geliştirme sırasında frontend’in gerçek adresini yazın; port numarası origin’in parçasıdır. Örneğin http://localhost:5173 ile http://127.0.0.1:3000 aynı origin değildir.

Karar vermeyi kolaylaştıran temel seçenekler şunlardır:


Kimlik doğrulama cookie ile yapılıyorsa credentials: true ekleyin ve origin değerini kesinlikle '*' yapmayın:


İstemci tarafında da istek credentials seçeneğiyle gönderilmelidir:

Preflight ve sık yapılan hatalar​

JSON gövdesi, özel başlıklar veya PUT, PATCH ve DELETE gibi yöntemler kullanıldığında tarayıcı önce OPTIONS preflight isteği gönderebilir. Express’te app.use(cors(...)) kullanmak, cors middleware’inin genel olarak bu isteklere de yanıt vermesini sağlar. Özel middleware sıralaması veya proxy kullanıyorsanız OPTIONS yanıtının engellenmediğini kontrol edin.

En yaygın hatalar şunlardır:

• Frontend adresini yalnızca alan adıyla yazmak; http, https ve port da kontrol edilmelidir.
• Cookie kullanan isteklerde wildcard origin kullanmak.
• CORS’u yetkilendirme sanmak. CORS, Postman veya sunucu tarafı istemcilerin API’ye erişimini engellemez.
• İzin verilen origin’i gelen Origin başlığından doğrulamadan aynen yanıtlamak.
• CORS middleware’ini route’lardan sonra eklemek. Genel kullanımda app.use(cors(...)) route tanımlarından önce yer almalıdır.

Tarayıcı konsolunda hata görürseniz önce isteğin Origin, yöntem ve gönderdiği özel başlıkları inceleyin. Ardından sunucu yanıtında Access-Control-Allow-Origin, gerekiyorsa Access-Control-Allow-Credentials, Access-Control-Allow-Methods ve Access-Control-Allow-Headers değerlerini kontrol edin.

Sık sorulan sorular​

Authorization başlığı gönderiyorsam credentials: true zorunlu mu?​

Yalnız JavaScript’in açıkça eklediği Bearer başlığı ile otomatik cookie taşıma aynı ayar değildir. Authorization başlığının preflight iznini doğrulayın; credentials seçeneğini oturum/cookie akışınıza göre belirleyin. İkisini tek anahtar gibi açmayın.

Özel yanıt başlığını neden fetch ile okuyamıyorum?​

Sunucunun Content-Disposition gibi bir başlığı göndermesi JavaScript’e otomatik olarak açıldığı anlamına gelmez. Gereken başlığı cors paketinin exposedHeaders seçeneğinde belirtin. allowedHeaders istemcinin göndereceği başlıkları, exposedHeaders ise okunabilecek yanıt başlıklarını düzenler.