İçeriğe geç
~/gamze_
cd ../blog

> cat ./blog/npme-iki-paket-yayinladim-clonelint-ve-minime-iconstan-ogrendiklerim.md

npm’e İki Paket Yayınladım: clonelint ve minime-icons’tan Öğrendiklerim

·8 dk okuma

#Yazılım Geliştirme#Npm

npm’de iki açık kaynak paketim var: React için bir ikon kütüphanesi olan icons ve yeni klonlanan bir projenin neden çalışmadığını bulan CLI aracı clonelint. İkisi de MIT lisanslı ve ücretsiz.

İnternetteki “npm paketi nasıl yayınlanır” yazılarının çoğu npm publish ile bitiyor. Oysa işin çoğu ondan önce ve sonra oluyor: pakete hangi dosyaların gireceği, React'in neden bağımlılık olmaması gerektiği, 2025'te değişen token kuralları, yanlış bir sürümü geri alıp alamayacağın. Bu yazıda iki paketimin gerçek package.json dosyalarını, npm pack çıktılarını ve yayın sürecini adım adım paylaşıyorum.

İki paket, iki farklı yol

Bu iki paketi birlikte anlatmamın sebebi şu: npm’e paket yayınlamanın iki ana yolunu temsil ediyorlar. minime-icons TypeScript ile yazılıp derleniyor; clonelint ise hiç derleme adımı olmadan, yazdığım JavaScript dosyalarıyla yayınlanıyor.

Neden yazdım?

minime-icons: Her ikon, birkaç props alan küçük bir React bileşeni. Paketteki gerçek bir örnek:

export const AbIcon = ({ size = 24, color = 'currentColor', strokeWidth = 2 }: IconProps) => {
  return (
    <svg
      width={size}
      height={size}
      viewBox="0 0 24 24"
      fill="none"
      stroke={color}
      strokeWidth={strokeWidth}
      strokeLinecap="round"
      strokeLinejoin="round"
    >
      <path d="M3 7V5h11v2M3 7v10a2 2 0 0 0 2 2h4M3 7h11" />
      <path d="M15 7h6M18 7v10" />
    </svg>
  )
}

color varsayılan olarak currentColor olduğu için ikon, içinde durduğu metnin rengini alıyor. Kullanımı da bu kadar basit:

import { HomeIcon, SearchIcon, UserIcon } from '@gamzesirin/minime-icons'

<HomeIcon />
<SearchIcon size={24} />
<UserIcon color="#7C3AED" strokeWidth={1.5} />

Paket ikonların yanında arama ve kategori yardımcıları da sunuyor: searchIcons('home'), getIconsByCategory('Media').

clonelint: “bende çalışıyordu” derdine tek komutluk çözüm

Yeni bir projeyi klonlayıp npm install dediğinde çalışmamasının sebepleri genellikle aynı: yanlış Node sürümü, eksik .env anahtarı, dolu bir port ya da çalışmayan bir veritabanı. clonelint projede zaten olan dosyaları (package.json, .nvmrc, .env.example, docker-compose.yml ve diğerleri) okuyup makineyle karşılaştırıyor:

$ npx clonelint

  clonelint · shop-api

  Runtimes
    ✖ Node.js 18.19.0 does not satisfy >=20 (package.json engines)
  Environment variables
    ✖ .env is missing 1 of 16 variables from .env.example: ENCRYPTION_KEY
      → Add them to .env.
  Ports
    ▲ Port 3000 (PORT) is already in use by node (PID 48213)
  Services
    ✔ Docker is running

  1 passed, 1 warning, 2 failed
  2 problems can be fixed automatically: clonelint --fix

Node, Python, PHP, Go ve Ruby projelerini tanıyor. --fix yalnızca güvenli düzeltmeleri yapıyor (bağımlılıkları kurmak, .env dosyasını şablondan oluşturmak gibi) ve mevcut değerlerin üzerine asla yazmıyor. --json çıktısıyla CI'da da kullanılabiliyor.

Hazırlık:

İsim seçimi

npm view clonelint

404 dönüyorsa isim boştur. İki pakette iki farklı yol seçtim:

  • clonelint: kapsamsız (unscoped) isim. Kısa ve akılda kalıcı ama başkası almadan önce davranmak gerekiyor.
  • @gamzesirin/minime-icons: kapsamlı (scoped) isim. @kullaniciadi/ altındaki her isim zaten senin; çakışma derdi yok. Karşılığında kurulum komutu biraz uzuyor.

İsim seçerken npm araması da önemli: keywords alanı aramada bulunmanı sağlıyor. clonelint için doctor, onboarding, dotenv, preflight gibi, insanların bu sorunu ararken yazacağı kelimeleri seçtim.

package.json: paketin kimlik kartı

İki paketin farkı en net package.json dosyalarında görünüyor. Aşağıdakiler yayınlanan sürümlerin gerçek alanları; yalnızca açıklama ve anahtar kelimeleri kısalttım.

clonelint: derlemesiz bir CLI

{
  "name": "clonelint",
  "version": "0.1.0",
  "type": "module",
  "bin": {
    "clonelint": "bin/clonelint.js"
  },
  "exports": "./src/index.js",
  "files": ["bin", "src"],
  "scripts": {
    "test": "node --test"
  },
  "engines": {
    "node": ">=18.3"
  },
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/gamzesirin/clonelint.git"
  }
}
  • bin: npx clonelint yazıldığında çalışacak dosya. npm bu dosyayı kullanıcının PATH'ine komut olarak bağlıyor.
  • exports: paketin bir de programatik API’si var. import { diagnose } from 'clonelint' bu satır sayesinde çalışıyor; aynı zamanda paketin içindeki diğer dosyalara dışarıdan erişimi kapatıyor.
  • type: module: bütün .js dosyaları ES modül olarak yorumlanıyor, import / export doğrudan kullanılabiliyor.
  • engines: neden tam olarak 18.3? Argümanları node:util içindeki parseArgs ile okuyorum ve bu fonksiyon Node 18.3'te geldi. Sürüm sınırını rastgele değil, kullandığın en yeni API'ye göre koy.
  • dependencies yok: npx ile çalışan bir araçta her bağımlılık ilk çalıştırmayı yavaşlatır. Semver karşılaştırmasını, .env ayrıştırmasını ve port kontrolünü kendim yazdım.

bin dosyasının ilk satırı şu olmalı, yoksa işletim sistemi dosyayı Node ile çalıştırması gerektiğini bilemez:

#!/usr/bin/env node
import { parseArgs } from 'node:util';

minime-icons: derlenen bir React kütüphanesi

{
  "name": "@gamzesirin/minime-icons",
  "version": "1.2.0",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.js"
    }
  },
  "files": ["dist", "README.md", "package.json"],
  "sideEffects": false,
  "scripts": {
    "build:lib": "tsup lib/index.ts --format cjs,esm --dts --clean --tsconfig tsconfig.build.json",
    "prepublishOnly": "npm run build:lib"
  },
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  }
}
  • tsup: tek komutla lib/index.ts dosyasından üç çıktı üretiyor: CommonJS (index.js), ES modül (index.mjs) ve TypeScript tipleri (index.d.ts).
  • exports: import kullanan bir Vite projesi .mjs dosyasını, require kullanan eski bir proje .js dosyasını alıyor. types koşulunun ilk sırada olması önemli; TypeScript koşulları sırayla okuyor.
  • main / module / types: exports alanını tanımayan eski araçlar için yedek.
  • sideEffects: false: bundler’a “bu paketteki bir dosyayı import etmek, kullanılmadıkça hiçbir şeyi değiştirmez” diyor. Böylece üç ikon kullanan bir proje, paketteki yüzden fazla ikonun hepsini taşımıyor.
  • peerDependencies: React’i pakete koymuyorum, kullanıcının projesindeki React’i kullanıyorum. Nedenini hemen aşağıda anlatıyorum.
  • prepublishOnly: npm publish çalışmadan hemen önce kütüphaneyi derliyor. Derlemeyi unutup eski dist klasörünü yayınlamak mümkün değil.

React neden peer dependency?

React’i dependencies içine koysaydım, kullanıcının projesinde iki ayrı React kopyası oluşabilirdi: biri uygulamanın, biri paketin. React bileşenleri ve hook'lar aynı React örneğiyle çalışmak zorunda; iki kopya "Invalid hook call" gibi açıklaması zor hatalara yol açar. Peer dependency "React'i ben getirmiyorum, sende olanı kullanırım, ama en az 16.8 olsun" demek.

Pakete ne giriyor?

Yayından önce en çok işe yarayan komut bu; hiçbir şey yayınlamadan pakete girecek dosyaları ve boyutu listeliyor:

npm pack --dry-run

clonelint’in çıktısının özeti:

npm notice 1.1kB LICENSE
npm notice 6.7kB README.md
npm notice 2.8kB bin/clonelint.js
npm notice 869B  package.json
npm notice 7.9kB src/checks/dependencies.js
...
npm notice package size: 19.0 kB
npm notice unpacked size: 52.8 kB
npm notice total files: 19

files alanı ve .npmignore hakkında doğru bilinen yanlışlar

Bu konuda internette çok karışık bilgi var. npm dokümantasyonuna göre kurallar şöyle:

  • files alanı bir izin listesi. Yazmazsan varsayılan değeri ["*"], yani her şey.
  • Kök dizindeki .npmignore, files alanını geçersiz kılmaz. İkisi birden varsa files kazanır.
  • .npmignore hiç yoksa npm .gitignore dosyasını kullanır.
  • package.json, README, LICENSE ve bin ile main alanlarında gösterilen dosyalar her durumda pakete girer. files içine README.md ve package.json yazmak zararsız ama gereksiz.
  • node_modules, .git, .npmrc ve lock dosyaları her durumda dışarıda kalır.

Yayından önce:

Yayınlanan bir sürüm numarası bir daha kullanılamıyor. Bu yüzden kontrolleri yayından önce yapmak, sonradan düzeltmekten çok daha ucuz.

clonelint: üç işletim sistemi, üç Node sürümü

clonelint’in testleri Node’un yerleşik test koşucusuyla çalışıyor; ekstra bir test kütüphanesi yok:

npm test   # node --test → 26 test

Ama bir CLI aracı için bu yeterli değil. Portu kullanan süreci bulmak için Windows’ta netstat, macOS ve Linux'ta lsof kullanıyorum; Linux'ta lsof kurulu değilse ss devreye giriyor. Bir platformda çalışan kod diğerinde kırılabilir. Bu yüzden GitHub Actions'ta bir matris kurdum:

strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]
    node: [18, 20, 22]
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node }}
  - run: npm test
  # Aracı kendi deposunda çalıştırarak duman testi
  - run: node bin/clonelint.js
  - run: node bin/clonelint.js --json

main dalına her push’ta ve her pull request’te 9 kombinasyon çalışıyor. Son iki adım hoşuma giden bir hile: araç kendi deposunu kontrol ediyor. Birim testleri geçse bile komut gerçek bir projede çöküyorsa burada yakalanıyor.

minime-icons: derlemeyi otomatiğe bağlamak

Derlenen bir pakette en sinsi hata, kaynağı güncelleyip dist klasörünü eski bırakmak. prepublishOnly betiği bunu engelliyor: npm publish her çalıştığında önce tsup derlemesi yapılıyor. Derleme hata verirse yayın da duruyor.

Yayın anı: npm publish

Kontroller tamamsa yayın tek komut:

npm publish

npm, 2FA doğrulaması ister; onayladığın an paket herkese açık. Birkaç dakika içinde başka bir makinede deneyebilirsin:

npx clonelint
npm install @gamzesirin/minime-icons

Scoped pakette tek fark: — access public

@gamzesirin/minime-icons gibi kapsamlı bir paketi ilk kez yayınlarken npm onu varsayılan olarak özel (private) yayınlamaya çalışır. Özel paketler ücretli bir özellik olduğu için ücretsiz hesapta yayın hata verir. Çözüm:

npm publish --access public

Bu bayrak yalnızca ilk yayında gerekli; sonraki sürümler mevcut erişim ayarını korur. Yine de unutmamak için package.json içine yazmak daha güvenli:

"publishConfig": {
  "access": "public"
}

Yayından sonraki ilk beş dakika

  • npm’deki paket sayfasını aç: README düzgün görünüyor mu, rozetler çalışıyor mu?
  • Temiz bir klasörde paketi kur ve en temel örneği çalıştır.
  • GitHub’da sürüm için bir etiket ve release notu oluştur.

Yanlış sürüm yayınladım, ne yapacağım?

npm’in geri çekme (unpublish) kuralları sık yanlış anlatılıyor. Gerçek kurallar şöyle:

  • İlk 72 saat içinde: başka bir paket ona bağımlı değilse istediğin zaman geri çekebilirsin.
  • 72 saatten sonra: yine geri çekebilirsin, ama üç koşulun hepsi sağlanmalı: hiçbir paket ona bağımlı olmayacak, son bir haftada 300'den az indirilmiş olacak ve tek bir sahibi olacak.
  • Sürüm numarası asla geri gelmez: clonelint@0.1.0 bir kez kullanıldıysa silsen bile bir daha yayınlayamazsın.
  • Paketin bütün sürümlerini silersen, yeni bir sürüm yayınlamak için 24 saat beklemen gerekir.

Çoğu durumda doğru çözüm silmek değil, yeni bir patch yayınlayıp hatalı sürümü kullanımdan kaldırmak:

npm deprecate clonelint@0.1.0 "Hatalı sürüm, lütfen 0.1.1 kullanın"

Bu sürümü kuran herkes terminalde uyarıyı görür, ama mevcut projeler bozulmaz.

Yayın öncesi kontrol listem

Her npm publish öncesinde bu listeden geçiyorum:

  1. Testler geçiyor mu? npm test, CI'daki bütün kombinasyonlar yeşil.
  2. Pakete doğru dosyalar mı giriyor? npm pack --dry-run çıktısında src ya da dist dışında beklemediğin bir şey yok; .env kesinlikle yok.
  3. Derleme güncel mi? Derlenen paketlerde prepublishOnly var.
  4. Tarball gerçek bir projede çalışıyor mu? npm pack ile oluşan .tgz dosyasını temiz bir projeye kurup en basit örneği dene.
  5. CLI’da shebang var mı? bin dosyasının ilk satırı #!/usr/bin/env node.
  6. React gibi framework’ler peer dependency mi? dependencies içinde React yok.
  7. Sürüm numarası doğru mu? Değişikliğin türüne göre patch, minor ya da major.
  8. README güncel mi? npm sayfasında ilk görünen şey README; kurulum ve en kısa kullanım örneği en üstte.
  9. Scoped paketse erişim public mi? publishConfig.access tanımlı.

İki paket bana farklı şeyler öğretti. minime-icons, bir kütüphanenin kullanıcının projesine nasıl uyum sağlaması gerektiğini: doğru exports, peer dependency, tree-shaking. clonelint ise az ama doğru şey yayınlamanın değerini: derleme yok, bağımlılık yok, 19 dosya.

Aklında küçük bir araç varsa bekleme. Her projede kopyaladığın o yardımcı fonksiyon, belki birinin aradığı paket.

Beğendiysen , kullandıysan GitHub’da bir yıldız bırakmayı unutma.

Bu yazı ilk olarak Medium'da yayımlandı. Yorum ve alkış için:

Medium'da aç