Bulut & SanallaştırmaOrta

pnpm Komutu: Node.js Paketlerini Yükleme ve Yönetme

Büyük Node.js projelerinde disk alanını optimize eden pnpm'in kurulumunu ve kullanımını adım adım öğrenin. npm'e alternatif olan bu araç, paketleri ortak bir depoda saklar.

L
Linuxize
1 görüntülenme
pnpm Komutu: Node.js Paketlerini Yükleme ve Yönetme

pnpm Nedir ve Neden Kullanılmalıdır?

Node.js projelerinde bağımlılık yönetimi yaparken, her proje aynı paketlerin kendi kopyalarını sakladığında beklenmedik şekilde çok fazla disk alanı tüketilebilir. pnpm (performant npm), bu sorunu paket dosyalarını içerik adresli paylaşılan bir depoda saklayarak ve her projeye bunları bağlantı yoluyla dahil ederek çözer. Bu sayede aynı paket versiyonunu kullanan 10 farklı proje, aslında diskte sadece bir kez saklanır.

pnpm, npm kayıt defterini (registry) kullanır ve package.json dosyalarıyla uyumlu çalışır. Bunun yanı sıra daha sıkı bağımlılık yönetimi sunar ve içsel workspace destekleri sayesinde monorepo projelerinde verimliliği artırır. Özellikle büyük ekipler ve çok sayıda projeyi aynı anda yöneten geliştiriciler için ideal bir çözümdür.

Önemli: pnpm, npm'in yerini almaz ancak disk kullanımı ve bağımlılık yönetimi konusunda önemli avantajlar sunar. Eğer projelerinizde disk alanı sorunu yaşıyorsanız veya bağımlılık çatışmalarından bıktıysanız pnpm mükemmel bir alternatif olacaktır.

pnpm Kurulumu (Linux, macOS, Windows)

Zorluk Seviyesi: Başlangıç (Beginner)

pnpm 11 kullanabilmek için Node.js 22.13 veya daha yeni bir versiyona ihtiyacınız vardır. Mevcut Node.js versiyonunuzu kontrol edin:

node --version

Eğer uygun bir Node.js versiyonuna sahip değilseniz, aşağıdaki kaynaklardan yardımcı olabilirsiniz:

1. Corepack ile Kurulum (Önerilen Yöntem)

Corepack, paket yöneticisi versiyonlarını yönetir ve projenizin package.json dosyasında kaydedilen pnpm versiyonunu otomatik olarak seçer. Öncelikle Corepack'ı güncelleyin:

npm install --global corepack@latest

Ardından pnpm şim (shim)ını etkinleştirin:

corepack enable pnpm

Projeniz için pnpm versiyonunu sabitleyin:

corepack use pnpm@latest-11

Bu komut, package.json dosyanıza aşağıdaki gibi bir packageManager girişi ekleyecektir:

{
  "packageManager": "pnpm@11.5.2"
}

Bu sayede ekip arkadaşlarınız ve CI sistemleri otomatik olarak aynı pnpm versiyonunu kullanacaktır.

2. npm ile Global Kurulum

Eğer tercih ederseniz, pnpm'i global olarak npm ile de kurabilirsiniz:

npm install --global pnpm@latest-11

Not: Bu yöntemle kurulan pnpm, projeye özel versiyon yönetimi yapmaz. Herkes aynı global pnpm versiyonunu kullanacaktır.

3. Bağımsız Kurulum (Node.js Gerektirmez)

Bağımsız kurulum, Node.js olmadan da pnpm kullanmanızı sağlar. Linux ve macOS için:

curl -fsSL https://get.pnpm.io/install.sh | sh -
Uyarı: Uzaktan bir betiği doğrudan shell'e yönlendirmek, ağdan gelen kodu kullanıcı olarak çalıştırmanıza neden olur. Üretim sistemlerinde bu betiği çalıştırmadan önce inceleyin veya önce indirip yerel dosyayı kontrol edin.

Windows PowerShell için:

Invoke-WebRequest https://get.pnpm.io/install.ps1 -UseBasicParsing | Invoke-Expression

Kurulum tamamlandıktan sonra yeni bir terminal açın ve pnpm versiyonunu kontrol edin:

pnpm --version
11.5.2

Proje Başlatma ve Paket Yükleme

Zorluk Seviyesi: Başlangıç (Beginner)

1. Yeni Bir Proje Başlatma

Yeni bir proje dizini oluşturun ve package.json dosyasını başlatın:

mkdir my-app
cd my-app
pnpm init

pnpm init komutu, paket metadata'si için sorular sorar ve sonuçları package.json dosyasına yazar. Eğer npm ile oluşturulmuş bir projeniz varsa, pnpm mevcut package.json dosyasını kullanabilir ve herhangi bir dönüştürme işlemine gerek yoktur.

2. Paket Yükleme

Bir çalışma zamanı bağımlılığı eklemek için pnpm add komutunu kullanın:

pnpm add express

Bu komut, paketi yükler, package.json dosyanızın dependencies bölümüne kaydeder ve pnpm-lock.yaml dosyasını oluşturur veya günceller.

Geliştirme araçları eklemek için -D (veya --save-dev) bayrağını kullanın:

pnpm add -D eslint

Belirli bir paket versiyonunu yüklemek için versiyon numarasını @ işareti ile belirtin:

pnpm add express@5.1.0

3. Mevcut Bir Projeyi Klonlama

pnpm kullanılarak oluşturulmuş bir projeyi klonladığınızda, tüm bağımlılıkları yüklemek için:

pnpm install

CI ortamlarında veya tekrarlanabilir ortamlarda pnpm-lock.yaml dosyasının değiştirilmemesini sağlamak için:

pnpm install --frozen-lockfile

Bu komut, package.json ve pnpm-lock.yaml dosyalarının uyumlu olmadığı durumlarda yeni bir bağımlılık ağacı oluşturmaya çalışmak yerine hata verir.

Global Paket Yükleme ve Komutları Çalıştırma

Zorluk Seviyesi: Başlangıç (Beginner)

1. Global Paket Yükleme

Komut satırı aracı olarak kullanılacak paketleri global olarak yükleyin:

pnpm add -g http-server

Eğer pnpm global ikili (binary) dizinini bulamazsa, aşağıdaki komutu çalıştırın:

pnpm setup

Ardından yeni bir terminal açarak global paket yükleme işlemini tekrarlayın. Uygulama bağımlılıklarını her zaman proje içerisinde yerel olarak saklayın ve global yüklemeleri sadece farklı projeler arasında kullanılan komutlar için saklayın.

2. Paket Komutlarını ve Betiklerini Çalıştırma

package.json dosyasındaki scripts bölümünde tanımlanan komutları çalıştırmak için:

{
  "scripts": {
    "start": "node index.js",
    "lint": "eslint ."
  }
}

Belirtilen komutu çalıştırmak için:

pnpm run lint

Eğer komut adı pnpm komutlarıyla çakışmıyorsa, run kelimesini atlayabilirsiniz:

pnpm start

Mevcut proje içerisinde yüklü olan bir paketin ikili dosyasını çalıştırmak için:

pnpm exec eslint .

Geçici olarak bir paketi çalıştırmak ve yerel olarak yüklememek için pnpm dlx komutunu kullanın:

pnpm dlx create-vite@latest my-app

pnpm exec, mevcut proje içerisinde yüklü olan bir bağımlılığı çalıştırırken, pnpm dlx geçici olarak bir paketi indirir ve komutunu çalıştırır.

npm'den pnpm'e Geçiş

Zorluk Seviyesi: Orta (Intermediate)

npm kullanılarak oluşturulmuş bir projeyi pnpm'e geçirmek için aşağıdaki adımları izleyin:

  1. npm kilit dosyasını pnpm kilit dosyasına dönüştürün:

    pnpm import

    Bu komut, mevcut package-lock.json dosyasını okuyarak pnpm-lock.yaml dosyasını oluşturur.

  2. Bağımlılıkları yükleyin:

    pnpm install

    Projenizin testlerini ve derlemelerini çalıştırarak her şeyin düzgün çalıştığından emin olun.

  3. npm kilit dosyasını kaldırın:

    rm package-lock.json

    pnpm-lock.yaml dosyasını commit edin ve CI komutlarını npm ci'den pnpm install --frozen-lockfile'e güncelleyin.

  4. Paket yöneticisini güncelleyin (isteğe bağlı):

    corepack use pnpm@latest

    Bu adım, projenizin package.json dosyasına pnpm versiyonunu kaydeder ve ekip arkadaşlarınızın aynı versiyonu kullanmasını sağlar.

pnpm Workspace'leri ile Çoklu Paket Yönetimi

Zorluk Seviyesi: İleri (Advanced)

pnpm workspace'leri, birden fazla paketi aynı depoda yönetmenizi sağlar. Bu yapı, monorepo projelerinde oldukça kullanışlıdır. Öncelikle, workspace yapılandırmasını tanımlayın:

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

Ardından, tüm workspace paketleri için bağımlılıkları kök dizinden yükleyin:

pnpm install

Tüm paketlerde tanımlı komutları çalıştırmak için:

pnpm --recursive run build

Belirli bir paket için komut çalıştırmak isterseniz, --filter bayrağını kullanın:

pnpm --filter web-app add zod
pnpm --filter web-app run test

--filter bayrağı, paketleri isim, dizin, bağımlılık ilişkisi veya değiştirilen dosyalar gibi çeşitli yöntemlerle seçmenizi sağlar. Bu özellik, büyük monorepo projelerinde ve CI ortamlarında oldukça kullanışlıdır.

Sık Karşılaşılan Sorunlar ve Çözümleri

1. pnpm: komut bulunamadı

Sorun: pnpm kurulumundan sonra komut bulunamıyor.

Çözüm: Shell'inizin PATH'ini yeniden yüklemesi için yeni bir terminal açın. Bağımsız veya global kurulum yaptıysanız, aşağıdaki komutu çalıştırın:

pnpm setup

Ardından terminali yeniden başlatın ve pnpm --version komutuyla versiyonu kontrol edin.

2. ERR_PNPM_UNSUPPORTED_ENGINE

Sorun: Kurulu pnpm veya proje paketlerinden biri farklı bir Node.js versiyonu gerektiriyor.

Çözüm: Node.js versiyonunu yükseltin veya bağımsız pnpm kurulumunu kullanın. pnpm 11, npm veya Corepack ile kurulduğunda Node.js 22.13 veya daha yeni bir versiyon gerektirir.

3. npm ile çalışan paket, pnpm ile çalışmıyor

Sorun: Bir paket npm ile çalışırken pnpm ile çalışmıyor.

Çözüm: Paket, npm'in daha düz node_modules yapısına güveniyor olabilir. Paketin kendi package.json dosyasında bildirilmeyen bir geçiş bağımlılığına sahip olabilir. Eksik paketi doğrudan bağımlılık olarak ekleyin.

4. CI ortamında ERR_PNPM_OUTDATED_LOCKFILE

Sorun: Commit edilen pnpm-lock.yaml dosyası package.json ile uyumlu değil.

Çözüm: Yerel olarak pnpm install komutunu çalıştırın, güncellenen kilit dosyasını inceleyin ve commit edin. Ardından CI ortamında pnpm install --frozen-lockfile komutunu çalıştırın.

Sonuç

pnpm, npm paket ekosistemini kullanırken disk alanını optimize eder ve daha net bağımlılık bildirimleri sunar. Eğer farklı iş akışlarını karşılaştırmak istiyorsanız, npm komut rehberine göz atabilirsiniz.

Artık pnpm kullanarak projelerinizi daha verimli bir şekilde yönetebilir ve disk alanından tasarruf edebilirsiniz. İyi kodlamalar!

Kaynak

Linuxize
İlgili Makaleler