NPM Paketini Versiyonlamak & Yayınlamak

8 min readMay 5, 2019

Kaynak neresi diye sorduğunuzu duyar gibiyim. Burası: https://docs.npmjs.com/creating-node-js-modules .

Basit olarak bir node uygulamasını modül haline getirmek şu aşamalardan geçiyor:

Bir npm paketi oluşturmak istediğimizde npm init komutunu kullanırız. Eğer hızlıca veri girmeden oluşturmak istersek -y anahtarını ekleriz. Ancak bu şekilde yaratacağımız paket scope(kapsam) içerisinde bir paket olmayacaktır. Nedir kapsam? Sizin npmjs adresinde oluşturduğunuz kullanıcı adınız altında paketlere erişilebilmesini sağladığınız bir isim uzayı(namespace, package name-paket adı-) diyebiliriz.

Kapsamsız bir paket oluşturursanız package.json içinde name anahtarı doğrudan paketin adını içerir.

“name” :  “essizAnahtarUreteci”

Kapsamlı olduğunda ise: @kapsamAdi/pakeAdi şeklinde bir isim olacaktır.

Önce scope(kapsam) içinde olan paketleme nasıldır ona bakalım. Mesela @angular kapsamı altındaki paketleri bulabiliriz. Scope altında paket yaratmak için:

npm init --scope=<your_org_name>

komutunu kullanıyoruz. Benim yaratacağım kapsamın adı @cemt olacak. Dikkat etmemiz gereken paketin adını sorduğunda <kapsam>/<paket adi> yazmamız gerekiyor. Örneğimde şöyle yazıyorum:

package name: (@cemt/scope) @cemt/node-ornegi

Yukarıdaki git adresini paketin adıyla aynı olsun diye node-ornegi diye değiştirdim. Şimdi bu paketin versiyonlanmasını da otomatik yapacak şekilde bir script yazalım.

Node paketiniz 0.0.1 olsun. Siz sürekli package.json içinde bu versiyon numarasını 1 arttırıp tekrar commit yapmak istemiyorsunuz. Otomatik versiyon artımını yapsın diye npm version komutu var. Buradaki örneğimizde versiyon metni 3 bölümden meydana geliyor.

MAJOR. MINOR. PATCH = büyük.küçük.yama

Bunu öğrenip bir müzik arası yapalım. Eğer hata gidermiş, performans kodlaması yapmış ama kodunuzu kullanan yazılımların kendilerini değiştirmelerini gerektirecek bir düzenleme yapmamışsanız “PATCH” değerini arttırın. Eğer sizin kodunuzu kullanan yazılımın önceki kodları çalışma hale geliyorsa bu değişimle birlikte “MAJOR” kısmını bir arttırın. Arasında kalan değişimlerde, yani yeni bir uç nokta(en point, fonksiyon adı, kullanılabilecek bir çıkış) eklemişseniz ve öncekilerinin major sürümle kaldırılacağını bildirecekseniz “MINOR” kısmını bir arttırın.

Şimdi Ümmü Gülsüm dinlenir değil mi?

Bu script sayesinde tüm değişimleri git’e ekleyecek ( git add .) ve yorum mesajıyla işaretleyecek ( git commit -m "mesajın kendisi") ve git’e göndermeden önce versiyonlayacak ve gönderecek bir script yazalım.

$ git add . && git commit -m “Değisikliklerin yorumlari burada” && npm version patch -m “Yeni versiyon oldu: %s” && git push

$ git add . && git commit -m "Değisikliklerin yorumlari burada" && npm version patch -m "Yeni versiyon oldu: %s" && git push

Git üstünde her bir değişimin “commit” olarak yer aldığını görüyoruz. npm version patch ile aslında sadece package.json içindeki version bilgisini değiştirmiyor, aynı zamanda git etiketi(tag) oluşturuyoruz.

Haydi gelin npm version ile arka planda etiket oluşturduğumuzu görelim.

Önce index.js dosyasında bir değişiklik yapalım ve git durumunu görelim.
Sonra git’e bu değişimi göndereceğiz diye işaretleyip
Üstüne bir yorum yazalım

Şimdi repository’miz(depomuz, havuzumuz) üzerindeki etiketleri(tag) görelim. Sonrada yeni bir npm version (major|minor|patch) -m "mesaj" yazarak git tarafından yerelde(local) yeni versiyon adında bir etiket(tag) oluşturulduğunu görelim. 1.0.10 İsimli etiketi yaratmış npm version komutu.

Eğer bir “git etiketi” yaratmadan versiyonlamak isteseydik

npm --no-git-tag-version version patch -m "mesaj gelsin"

komutunu kullanmamız gerekirdi.

npm version patch -m “mesaj metni. versiyon: %s”

npm version ile neler olduğuna git log komutuyla bakalım:

Demek oluyor ki; npm version arka tarafta bize bir etiket oluşturuyor. Şimdi bu haliyle git üstüne gitmediğini biliyoruz çünkü hiç git push yapmadık. Eğer git push yaparsak sadece commit mesajı olarak master isimli dala(branch) kayıt edildiğini görmüştük.

git push ile sadece commit edilmiş hallerini master dalına(branch) göndermiş oluruz. Aşağıda git push sadece master dalında mesajlarını gördüğümüz 2 commit yaratmış olacak.

Şimdi de etiketimizi göndererek git üstündeki durumu gözden geçirelim:

Yerelde(local) ve uzakta(remote) kayıtlı etiketleri listeleyip son versiyonlamayı gösterelim:

Uzakta 1.0.11 yokken yerelde olduğunu görüyorsunuz. git push --tags master ile eşitlemiş oluyoruz.

Referanslar

package.json’ı anlamak: https://docs.npmjs.com/files/package.json
npm paketini versiyonlamak için: https://docs.npmjs.com/cli/version
git üstündeki hareketleri görmek için git log komutunu kullanıyoruz: https://git-scm.com/book/en/v1/Git-Basics-Viewing-the-Commit-History
git üstünde etiketleri görüntülemek ve yönetmek için
List all the tags: $ git tag
Search tags for a particular pattern: $ git tag -l <tag-pattern>
Show a tag data: $ git show <tag-name>
Create a Lightweight Tag: $ git tag <tag-name>
Create an Annotated Tag: $ git tag -a <tag-name> -m <tag-message>
Create a tag for a specific commit: $ git tag -a <tag-name> <commit-checksome>
Push a specific tag to remote: $ git push origin <tag-name>
Push all the tags to remote: $ git push origin --tags
Checkout a specific to local: $ git checkout -b <branch-name> <tag-name>
kullanıyoruz: https://www.kunal-chowdhury.com/2016/10/git-cheatsheet-git-tags.html
package.json içeriğini başlık başlık örnekleriyle bu adresten okuyabilirsiniz. Veya npmjs adresinden.

The package.json guide

The package.json file is a key element in lots of app codebases based on the Node.js ecosystem.

flaviocopes.com

Şimdi Yayınlayalım

Önce npm bizi tanıyor mu diye sormak için npm whoami komutunu kullanalım

Bizi tanımadığına göre ister npm adduser ile ister npm login npm’e giriş yapalım. Giriş yapmak için hesap oluşturmalısınız. Bu hesabı npmjs adresinde yaratıp giriş yaptıktan sonra console üstünden de giriş yapmanız gerekecek.

npm adduser ile giriş yaparsak:

npm login ile giriş yapmak için önce npm logout kullanalım ve:

Eğer npm paketlerinizi özel bir npm sunucusunda (private npm server) saklamak istiyorsanız (örn. Verdaccio, YarnPkg vs) bu kez login olurken paket kütüğünüzün adresini --registry=http://paket_sunucu_ip:port şeklinde belirtmelisiniz. Bunu yerelde kurulu verdaccio sunucusu için şöyle yaparsınız:

$ npm login --registry=http://localhost:4873

Sonra giriş başarılı olduğunda bir paket yayınlayalım ama paket için kullandığım scope adı(@cemt) maalesef npmjs adresindeki kullanıcı adım ile aynı olmadığı için package.json dosyasındaki adı değiştirip tekrar versiyonlayıp etiketi git üstüne push etmeliyim:

lenovo@DESKTOP-TDG2P1H C:\Temp\scope 
$ git status 
On branch master 
Your branch is ahead of ‘master/master’ by 2 commits. 
.....
 
 modified: package.json 
 
no changes added to commit (use “git add” and/or “git commit -a”) 
 
lenovo@DESKTOP-TDG2P1H C:\Temp\scope 
$ git add . && git commit -m “scope adini @cemtopkaya olarak degistim.” 
.....
[master 25673a0] scope adini @cemtopkaya olarak degistim. 
 1 file changed, 2 insertions(+), 2 deletions(-) 
 
lenovo@DESKTOP-TDG2P1H C:\Temp\scope 
$ npm version minor -m “Cunku npmjs adimi scope adi olarak kullanabilirim” 
v1.1.0 
 
lenovo@DESKTOP-TDG2P1H C:\Temp\scope 
$ git ls-remote --tags 
From https://github.com/cemtopkaya/node-ornegi.git 
5a0dfce3f2d38e7a5ecec893f5fbbb7cf79ba898 refs/tags/v1.0.1 
1b21720f8f63c62a07bb5a5a08d45861292cead3 refs/tags/v1.0.10 ...............
cded7a850839e5628569c749d7b2bd53337598ae refs/tags/v1.0.9 
 
lenovo@DESKTOP-TDG2P1H C:\Temp\scope 
$ git tag 
v1.0.1 
v1.0.10 
v1.0.11 
.....
v1.0.8 
v1.0.9 
v1.1.0 
 
lenovo@DESKTOP-TDG2P1H C:\Temp\scope 
$ git push --tags master 
......
remote: Resolving deltas: 100% (4/4), completed with 2 local objects. 
To https://github.com/cemtopkaya/node-ornegi.git 
 * [new tag] v1.1.0 -> v1.1.0 
 
lenovo@DESKTOP-TDG2P1H C:\Temp\scope 
$ git ls-remote --tags 
From https://github.com/cemtopkaya/node-ornegi.git 
5a0dfce3f2d38e7a5ecec893f5fbbb7cf79ba898 refs/tags/v1.0.1 
1b21720f8f63c62a07bb5a5a08d45861292cead3 refs/tags/v1.0.10 
3d47bf3e304bb42a7a92257836e6353c403f2e82 refs/tags/v1.0.11 .............
a334af69015e10a51522a047af75e97bdd0ea260 refs/tags/v1.1.0

Şimdi npm publish --access public komutuyla yayınlayalım. Paketimizi npmjs web sitesi üstünde görebileceğimiz gibi npm info @cemtopkaya/node-ornegi komutuyla da görebiliriz.

npm publish --access public && npm info @cemtopkaya/node-ornegi

https://www.npmjs.com/package/@cemtopkaya/node-ornegi Adresinde bulabiliriz (tabi silmezsem). Kanıtı aşağıdaki ekran görüntüsündedir ;)

Özel bir npm sunucunuz varsa (verdaccio, yarnpkg vs gibi) kurulum ve kullanımı için güzel bir makale : https://medium.com/@rossbulat/publish-private-npm-packages-with-proxy-registry-verdaccio-56b769bca659

Verdaccio — Kullanıcı Kayıtlı mı?

http://192.168.13.183:4873/-/user/org.couchdb.user:jenkins

Verdaccio — Paket Ön Belleğe Alınmış mı? (cached)

Bir paketi indirirken --registry=http://localhost:4873 diye ön belleğe alınması için yerelde çalışan (veya başka bir sunucuda) verdaccio makinanızı gösterdiğinizde önce kendi üstünde o paketin olup olmadığına bakar varsa hemen döner yoksa kendinde kayıtlı npm paket sunucu adreslerine sorar ve onlarda bulursa gelen paketi kendinde yedekler ve istemciye paketi döner. Böylece bir sonraki aynı paketi yükleme isteğinizde uzak sunuculara gitmez, kendindekini döner.

Verdaccioda paketlerle ilgili işlemleri gören api dosyası package.ts.

verdaccio/verdaccio

📦🔐A lightweight private npm proxy registry. Contribute to verdaccio/verdaccio development by creating an account on…

github.com

http://localhost:4873/-/verdaccio/packages

Eğer npm paketlerinizi sürekli npmjs ten çekmek yerine bir kere kendi npm sunucunuz tarafından yedeklensin istiyor ve sonrasında sürekli buradan daha hızlı çekebilmek istiyorsanız Addy Osmani güzel bir makale yazmış: https://addyosmani.com/blog/using-npm-offline/

Test Uygulamasında Görelim

Bir başka npm paketi oluşturup içinde bu paketi kullanıyoruz:

Referanslar:

Npm Config

Yukarıda komut satırlarında --registry anahtarıyla verdiğiniz bilgileri proje özelinde .npmrc dosyasında veya globalde npm config set ile tanımlayabilirsiniz. Globalde npm ayarları %UserProfile%\.npmrc dosyasında bulunur.

Npm Ayarlarını Listeleyelim

npm config ls

Npm Ayarını Silmek

npm config rm <anahtar>

Npm Ayarı Eklemek

$ npm config set <anahtar> <deger>

$ npm config set registry          http://192.168.56.1:4873/ 
$ npm config set @kapsam:registry  http://10.16.16.15:4873/

Proje Bazlı .npmrc Dosyası & Npm Ayarları ( --userconfig)

Bulunduğu dizinde .npmrc dosyası olması yeterli. Npm önce yakınlardaki .npmrc varsa içindeki ayara göre harekete geçer. Bulamazsa globaldeki .npmrc ye kadar gider. Bu yüzden --userconfig ile .npmrc dosyasının dosya yolunu belirtiriz.

$ npm config set  \
   registry http://192.168.56.1:4873  --userconfig ./.npmrc  && \
npm config set  \
   @kapsam:registry  http://192.168.13.33:4873 --userconfig ./.npmrc