İlk NPM Paketinizi Oluşturmanın En Kolay Yolu

Bu kılavuz, bir mikro paket kullanarak NPM paketinizi baştan sona oluşturmanın ve yayınlamanın en kolay süreci boyunca size yol gösterecektir.

Biraz da microbundle hakkında konuşalım. Bunu özellikle basit kitaplıklar için etkili buluyorum çünkü yapılandırma konusunda endişelenmenize gerek yok, bu da paketinizi geliştirmeye odaklanmanıza olanak tanıyor.

İşte özelliklerinin kısa bir listesi:

• Yerleşik yapılandırmalar; tek yapmanız gereken package.json bir "dışa aktarma" alanı eklemek
• tsconfig.json olmadan kullanıma hazır TypeScript desteği
• Çoklu çıktı formatları (CJS, UMD ve ESM)
• Yerleşik Terser sıkıştırması

Temel olarak microbundle , rollup.js'nin üzerine inşa edilmiştir. Bu makalede bahsedeceğimden daha karmaşık kitaplıklarınız varsa, saf rollup.js yapılandırmasını kullanmayı düşünebilirsiniz.

Paketinizi Başlatma

Örnek olarak, iki sayıyı toplamak için yalnızca bir sum fonksiyonunu dışa aktaracak basit bir kitaplık oluşturalım.

1. Proje için bir klasör oluşturun ve package.json oluşturmak için npm init varsayılan değerlerle çalıştırın.

   
   

2. src klasöründe index.ts oluşturun

    // src/index.ts export function sum(a: number, b: number) { return a + b; }

3. microbundle yükle

   npm i -D microbundle

   
   

4. package.json aşağıdaki değerlerle güncelleyin:

    // package.json ... "type": "module", "source": "src/index.ts", // your source code "exports": { "types": "./dist/index.d.ts", // TypeScript declaration file "require": "./dist/index.cjs", // CommonJS entry point "default": "./dist/index.esm.js" // ES Module entry point }, "main": "./dist/index.cjs", // where to generate the CommonJS bundle "module": "./dist/index.esm.js", // where to generate the ESM bundle "unpkg": "./dist/index.umd.js", // where to generate the UMD bundle "types": "./dist/index.d.ts", // TypeScript declaration file for the package "scripts": { "build": "microbundle", // compiles "source" to "main", "module", "unpkg" "dev": "microbundle watch" // re-build when source files change } ...

5. Derleme betiğini çalıştırın

   npm run build

   
   

   Çıktı tam olarak package.json bildirdiğimiz dosyaları içermelidir.

   

Ve işte, ilk paketimizi yaptık. Daha karmaşık senaryolara bir göz atalım.

Kitaplığınıza React Ekleme

React'ı kütüphanenize getirmek istiyorsanız microbundle kullanmaya devam edebilirsiniz ancak artık build komutunuz şu şekilde görünmelidir:

 microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx

Gelecekte kolaylık sağlamak için package.json komutu build betiğine ekleyin:

 // package.json ... "scripts": { "build": "microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx" } ...

Kullanıcı Arayüzü Bileşenleri için Storybook'u Kullanma

Bir kullanıcı arayüzü kitaplığı oluştururken bileşenleri geliştirebileceğiniz, görselleştirebileceğiniz ve belgeleriniz için demo bileşenleri sağlayabileceğiniz bir sanal alana ihtiyacınız olabilir.

İşte hikaye kitabı geliyor. Bileşenlerinizin çeşitli durumlarını kolayca tanımlayabileceğiniz, kendi kullanışlı arayüzü ve paketleyicisine sahip bir sanal alan. Bileşen durumunuzun her bir yakalamasına "hikaye" adı verilir.

Belgelerinden alınan bu resim neye benzediğini gösteriyor:

Storybook'u yüklemek oldukça basittir; sadece kütüphanenizin içindeki komutu çalıştırın:

 npx storybook@latest init

Bu komut, Storybook için gerekli tüm bağımlılıkları yükleyecek, çalıştırılacak komut dosyalarını ekleyecek ve Storybook'u package.json içinde oluşturacak, varsayılan yapılandırmaya sahip bir .storybook klasörü oluşturacak ve bazı hikaye örneklerini src/stories klasörüne ekleyecektir.

Şekillendirmeyi Kitaplığınıza Entegre Etme

Stili iki yoldan biriyle ekleyebilirsiniz: CSS dosyası veya JS'de CSS. CSS dosyası kolay özelleştirmeye izin verir ancak ayrı bir ekleme gerektirir; JS'deki CSS ise stillendirmeyi basitleştirir ancak paket boyutunu artırır.

• CSS dosyası

  Src dizininde bir CSS dosyası oluşturun ve bunu root react bileşen dosyasına aktarın:

   // src/index.tsx import './styles.css'; export const MySuperComponent = () => { return ( <h1 className="title">Hi there!</h1> ) };

  
  

  Şimdi build komutunu tekrar çalıştıralım.

   npm run build

  
  

  Ve içe aktarılan styles.css dosyanız dist klasöründe oluşturulacaktır:

  

  Harika! Gerekli stillere sahip bir CSS dosyası elde ettik. Ancak bu çözümde ufak bir rahatsızlık var. Paket kurulduktan sonra CSS dosyasının ayrıca eklenmesi gerekmektedir.

  
  

  Bu nedenle, kitaplığınızın kullanıcılarının CSS dosyanızı işlemek için bir CSS yükleyicisi (örneğin, web paketi için bir CSS yükleyicisi) kullanması gerekecektir ve kullanımları şu şekilde görünecektir:

   import { MySuperComponent } from 'my-super-library'; import 'my-super-library/dist/styles.css'; export const App = () => { return ( <MySuperComponent /> ); }

  
  

• JS'de CSS

  Bu amaçla styled-component gibi kütüphaneleri kullanabilirsiniz. Ve şöyle görünecek:

   import styled from 'styled-components'; const Title = styled.h1` font-size: 30px; font-weight: bold; `; export const MySuperComponent = () => { return ( <Title>Hi there!</Title> ) };

  Bu çözüm sayesinde kullanıcıların bir CSS dosyasını içe aktarmalarına ve projeleri için özel bir yükleyici eklemelerine gerek kalmayacak. Kitaplığı yükledikten sonra bileşen kendi stiliyle birlikte gelecektir. Ancak bu, paket boyutunu artıracak ve kullanıcıların CSS seçicileri kullanarak öğeleri özelleştirmesini zorlaştıracaktır.

Size en uygun seçeneği seçin. CSS dosyasını kullanmayı tercih ediyorum çünkü bu, kullanıcıların herhangi bir öğeyi CSS seçicilerle özelleştirmesine olanak tanıyor, paket boyutunu etkilemiyor ve daha hızlı çalışıyor.

Ayrıntılı bir README.md Dosyası Geliştirme

README.md dosyası kitaplığınız, nasıl kurulacağı, temel kullanımı ve sahip olduğu özellikler hakkında bilgi sağlar. Bu genellikle geliştiricilerin deponuzla veya NPM paketinizle karşılaştıklarında okudukları ilk dosyadır, bu nedenle kısa ve bilgilendirici olmalıdır.

Aşağıdaki sırayla bir yapı oluşturmayı seviyorum:

1. Başlık
2. Süper kısa paket açıklaması
3. Süslü istatistik rozetleri ( shields.io )
4. Kitaplığınız bir kullanıcı arayüzü bileşeniyse bir ekran görüntüsü ekleyin veya CodeSandbox'ta bir demo bağlantısı sağlayın
5. Özellikler listesi
6. Yükleme Rehberi
7. Kullanımı olan kod parçaları
8. Kitaplığınızın yapılandırma için kabul ettiği seçenekler ve destekler

İlham almak için paketlerimdeki dot-path-value ve react-nested-dropdown gibi README.md dosyalarının örneklerine başvurabilirsiniz.

Bağımlılık Yönetiminde Gezinme

Bu önemli bir kısım çünkü yanlış yaparsanız kullanıcılar sürüm çakışmaları veya başka sorunlarla karşılaşabilir ve kitaplığınızı kaldırmak zorunda kalabilirler. Şimdi bağımlılık türleri arasındaki temel farklara bir göz atalım.

• "devDependencing'ler" yalnızca geliştirme amaçlıdır ve paketinize dahil edilmeyecektir. Örneğin, kullanıcıların kullanmasına gerek olmayan microbundle paket paketini yüklediyseniz, bunu devDependencing'de tutun; pakette görünmeyecektir.

• "bağımlılıklar" paketle birlikte kurulacaktır. Paketinizin kullanıcıların projelerinde çalışması için ihtiyaç duyduğu bağımlılıkları ekleyin. "React" gibi bazı bağımlılıkların kullanıcının projesine önceden yüklenmiş olabileceğini unutmayın. Paketinizde yinelenen bir "tepki" bulunması paket boyutunu artırabilir. “Akran Bağımlılıkları”nın işe yaradığı yer burasıdır.

• “peerDependencing'ler” paketinizin kullandığı ancak paketinize dahil etmeyeceği bağımlılıklardır. Paketiniz, kullanıcının projesinde sahip olduğu bağımlılığın sürümünü kullanacaktır.

  
  

  Temel olarak, eğer ekosistemi için bir kütüphane oluşturuyorsak, bir eş bağımlılığı belirtmeliyiz. Örneğin, bir React bileşeni oluşturuyorsanız React'ı eş bağımlılığı olarak ayarlayın. Takvimli bir React bileşeni geliştiriyorsanız, React'ı ve bir tarih hesaplama kütüphanesini (örneğin, date-fns)peerDependencing'ler olarak ekleyin.

  
  

  Kullanıcının projesinde belirtilen eş bağımlılığı yoksa, npm install komutu bir uyarı görüntüler ancak bağımlılığı otomatik olarak yüklemez.

Nasıl göründüğüne dair sadece küçük bir örnek:

 // package.json ... "dependencies": { // libraries which will be installed along with your library "clsx": "^1.2.1" // just library for className combining }, "peerDependencies": { // user should have these packages installed "react": "^16.8.0 || ^17.0.0 || ^18.0.0" // user should have react 16.8+ version }, "devDependencies": { // won't be in user's bundle, these libraries just for your developing needs "@types/react": "^18.2.33", "react": "^18.2.0", // in case if we are using storybook, we need actual react library to render our components there "microbundle": "^0.15.1", }, ...

Paketiniz için GitHub'u Kullanma

Bir NPM paketi yayınlıyorsanız, bu onun herkese açık olacağı anlamına gelir (eğer ücretsiz bir hesabınız varsa). Kullanıcılardan geri bildirim toplamak amacıyla orijinal kodunuz için bir GitHub deposu oluşturabilirsiniz. İnsanlar orada sorun yaratabilir ve paketiniz hakkında sizinle iletişim kurabilir. Ayrıca yayınlarınızı tanımlayabilir ve birkaç yıldız kazanabilirsiniz!

Bu adımı kesinlikle atlayabilirsiniz ancak bu, geliştirici kültürünün ayrılmaz bir parçasıdır ve açık kaynağa değerli bir katkı olabilir.

Paketin Yayınlanması ve Bakımı

Paketinizi yayınlamadan önce package.json dosyanızın doğru şekilde yapılandırıldığından emin olmanız önemlidir. İzlenecek bazı önemli adımlar şunlardır:

1. Kitaplığınızın temel işlevlerini adlandırın ve açıklamaya çalışın. Örneğin:

    "name": "react-color-picker"

   
   

2. GitHub deposu bilgilerini ekleyin (varsa):

    ... "homepage": "https://github.com/{your_repository}", "repository": { "type": "git", "url": "https://github.com/{your_repository}" }, "bugs": { "url": "https://github.com/{your_repository}/issues" }, ...

   
   

3. files yapılandırın:

    ... "files": [ "dist", ], ...

   Kütüphaneniz kurulduğunda node_modules dahil edilecek dosyaları belirtmelisiniz. Genellikle dist klasörünün dahil edilmesi yeterlidir.

   
   

4. keywords ekleyin:

   Anahtar kelimeler paketinizi tanımlayan ve NPM tarafından aramalar ve öneriler için kullanılan bir dizi dizedir. İnsanların arama yaparken kullanacağını tahmin ettiğiniz, paketinizle alakalı kelimeleri seçin. sum kütüphanemiz için anahtar kelimeler oluşturalım:

    ... "keywords": ["typescript", "math", "sum", "numbers", "arithmetic", "calculator", "calculation"] ...

   Kullanıcılar sıklıkla "matematik için yazı tipi kitaplığı" veya "tepki takvimi seçici" gibi terimleri arattıkları için teknolojilerinizi belirtmeniz önemlidir.

   
   

5. Henüz yapmadıysanız bir NPM hesabı oluşturun ve terminalinizde npm login çalıştırın; hesabınızın kimliğini doğrulamak için talimatları izleyin. Varsayılan olarak paketinizin sürümü 1.0.0 olacaktır; package.json dosyasından kontrol edebilirsiniz. 0.0.1 olarak değiştirmenizi öneririm.

   
   

6. npm publish çalıştırın ve işiniz bitti! Gelecekte sürümü güncellemek için, sürümü artırmak üzere npm version patch komutunu kullanın ve ardından güncellenen paketi npm publish ile yayınlayın.

Çözüm

Gördüğünüz gibi kendi kütüphanenizi oluşturmak çok kolay! Temel olarak, paketi oluşturmak ve sürdürmek için ihtiyacınız olan tek şey budur. Kitaplığınızı microbundle ile sınırlandırmakta zorlanıyorsanız rollup.js'yi daha spesifik bir yapılandırmayla kullanmanızı öneririm.

NPM paketleri oluşturmak ve açık kaynağa katkıda bulunmak, tüm beceri seviyelerindeki geliştiriciler için ödüllendirici ve değerli bir deneyimdir. Kodunuzu toplulukla paylaşmanıza, çok fazla deneyim kazanmanıza ve çalışmalarınızdan oluşan bir portföy oluşturmanıza olanak tanır.