Lerna & Rollup & Typescript ile React Kütüphanesi

Bu yazımda RollupJS ve LernaJS kullanarak bir çok iş alanı(workspace) ile çalışan Typescript ile paylaşıma hazır kütüphane geliştirmekten bahsedicem. Facebook’un sunduğu create-react-app projesi sayesinde React projesi oluşturup bunu derlemek basittir ve sadece tek komutla halledilebilir ancak işler kütüphane geliştirmeye gelince biraz farklılaşmaktadır. Yazıda bahsedilen konular:

• RollupJS
• LernaJS
• Typescript
• Yarn Workspaces

1. LernaJS Nedir ?

LernaJS sayesinde büyük projeleri tek bir depoda(repository) efektif bir şekilde tutabiliriz. Büyük ve karmaşık projeler birden fazla depoda ayrı ayrı tutulabilir ancak bu da projenin izlenmesi, kodun paylaşılması, takip ve test edilmesini zorlaştırmaktadır. Lerna bu soruna çözüm bularak birden fazla yapıya bölünen projeleri tek bir GIT deposunda tutarak bunları sistematik bir şekilde yönetmeyi sağlar. LernaJS GIT ve NPM ile birlikte çalışarak, çalışma ortamını optimize etmektedir. Kendi sitesine göz atmak isterseniz: LernaJS

2. RollupJS Nedir ?

Rollup javascript için yapılmış modül paketleyicisidir. Bir nevi Webpack ile aynı işlevi görmektedir. Webpack ile karşılaştırılırsa performansları neredeyse eşittir ancak Rollup’un konfigurasyonu Webpack’e göre daha hafiftir. Modül paketleyicileri kaynak kodu tek bir dosyada birleştirerek minimize edilmiş Javascript kodu vermektedirler. Ayrıca Rollup bizim için farklı modül sistemlerine göre çıktılar verebilmektedir. Örneğin CommonJS,UMD ve ES. Rollup’un sitesi için: RollupJS

3. Yarn Çalışma Alanları (Workspace)

Yarn çalışma alanları projeyi birkaç çalışma alanına bölmemizi sağlar. Böylelikle tek bir yarn install komutu ile bütün projelere gerekli olan kütüphaneler yüklenebilir. Yarn 1.0 ile birlikte gelmiştir. Detaylı bilgi için: Yarn Workspaces

1. Proje Yapısının Oluşturulması

Proje oluşturulurken kütüphanenin test edilmesi adına JS ve TS ile kütüphaneyi kullanılan iki örnek proje eklenecektir ve bunlar tek bir dizinde olacaktır. Ayrıca kütüphanenin bağımlı olduğu 3.parti kütüphanelerin Rollup ile birlikte kullanımının gösterilmesi için Konva kütüphanesi kullanılacaktır. Konva Javascript ile iki boyutlu çizimler yapmamızı sağlayan React için ayrı paketi olan (react-konva) kütüphanedir.

1.1. Lerna’nın Yüklenmesi ve Çalıştırılması

Lerna’nın yüklenmesi için aşağıdaki komut çalıştırılır. Bu komut ile Lerna kalıcı olarak sistemimize yüklenmektedir.(NOT: lokal olarak yüklemediğimizden yönetici izinleri isteyebilir)

npm install -g lerna

Lerna ile proje hazırlanır ve gerekli dosyalar oluşturulur:

lerna init

1.2. Dizin Yapısının Hazırlanması

Projenin dizin yapısı aşağıdaki gibi oluşturulur:

./react-ts-library
|  |-- examples/
|  |-- packages/ (lerna init oluşturmaktadır)
|  |   |-- react-ts-library/
|  |-- lerna.json (lerna init oluşturmaktadır)
|  |-- package.json (lerna init oluşturmaktadır)

Bu yapıda examples/ dizini kütüphaneyi test edeceğimiz JS ve TS ile yazılmış React projelerini, packages/ dizini ise kütüphanemizi içermektedir. lerna.json dosyası ise Lerna’nın konfigurasyon dosyasıdır.

2. Projenin Konfigure Edilmesi

Kök dizinimizde proje için ayarlamalar yapmamız gerekir bunun için lerna.json ve package.json dosyaları değiştirilir.

2.1. Lerna’nın Ayarlanması

Kök dizindeki lerna.json dosyası aşağıdaki gibi değiştirilir:

{
  "npmClient": "yarn",
  "useWorkspaces": true,
  "version": "independent"
}

Burada kullandığımız terimlerin anlamı ise:

• npmClient: Lerna’ya npm komutunu olarak yarn’ı kullanması söylenir.
• useWorkspaces: Lerna’nın yarn’ın çalışma alanlarını kullanması istenir.
• version: Oluşturduğumuz projelerin (kütüphane, ve test edeceğimiz projeler) birbirinden bağımsız sürümlerinin olduğunu belirtir.

2.2. Package.json Dosyasının Ayarlanması

Kök dizindeki package.json dosyası aşağıdaki gibi değiştirilir.

{
  "name": "root",
  "private": true,
  "workspaces": [
    "packages/*",
    "examples/*"
  ],
  "scripts": {
    "build": "lerna run build --scope react-ts-library",
    "watch": "lerna run watch --scope react-ts-library",
    "start": "lerna run start --scope react-ts-example",
    "package": "lerna exec --scope react-ts-library -- npm pack"
  },
  "devDependencies": {
    "lerna": "^4.0.0"
  }
}

Burada önemli yerleri belirtmemiz gerekirse;

• private parametresi kütüphaneyi yanlışıkla paylaşmamızın önüne geçmektedir.
• workspaces Yarn’a çalışma alanlarını belirtmektedir.

Scripts altına yazılanlar yarn komutuna verilen parametrelerin ne işlev yapacağını belirtmektedir. Örneğin kök dizinde komut satırından yarn build komutu girildiğinde lerna run build — scope react-ts-library komutu çalışmaktadır. Bu komut ise lerna’nın react-ts-example projesinin olduğu yere gitmesini ve buradaki package.json dosyası içerisinde build için tanımlanmış komutu çalıştırmasını sağlar.

3. Kütüphanenin Oluşturulması

Kütüphane yarn paketi olarak oluşturulur ardından kök dizine geri gidilir:

cd packages/react-ts-library
yarn init -y
cd ../../

3.1. Üçüncü Parti Paketlerin Kütüphaneye Eklenmesi

Kök dizinden lerna’ya scope parametresi vererek işlem yapacağımız projeyi seçebiliriz. Bir projeye paket eklerken lerna add veya o projenin olduğu dizine gidip yarn add komutu kullanılabilir. Lerna ile paketlerin yüklenmesi için:

lerna add react --scope react-ts-library --peer;
lerna add react-dom --scope react-ts-library --peer;

Bu komut ile React ve React-DOM paketlerini projemize ‘peer’ olarak ekliyoruz. Bunun anlamı kütüphanemizin React, React-DOM paketlerine ihtiyacı olduğunu ve kütüphaneyi kullanmak isteyen birinin bu paketleri kendi yüklemesi gerektiğidir çünkü React kütüphanesi oluşturduğumuzdan dolayı iki tarafında(kullanıcı ve kütüphane) React paketine ihtiyacı vardır.

React paketleri eklendikten sonra yarn ile de paket eklemek ve geri kalan kütüphanelerin yüklenmesi için proje klasörüne gidilir ve paketler yüklenir.

cd packages/react-ts-library/
yarn add -D rollup typescript rollup-plugin-typescript2 @rollup/plugin-commonjs react react-dom

Bu paketler aşağıdaki işlemlerde kullanılmaktadır:

• rollup: Kütüphanemizi paketlemek için. (Bundling)
• rollup-plugin-typescript2: Rollup’un Typescript ile çalışabilmesi için gereken rollup eklentisi.
• rollup/plugin-commonjs: Rollup’ta kullanılmak üzere CommonJS modüllerini ES modüllerine dönüştüren eklenti.
• typescript: Typescript derleyicisi

NOT: Burada yarn’a verilen -D parametresi paketlerin sadece geliştirme zamanında (development) kullanılacağını belirtir ayrıca react ve react-dom paketlerini tekrar ekleme sebebimiz bu paketlerin lerna ile eklendiğinde peer olarak eklenmesidir. Burada React paketlerini sadece geliştirme zamanında kullanılmak üzere ekleyerek Typescript derleyicisinin hata vermesini engellemiş oluruz.

3.2. Typescript ve Rollup’un Ayarlanması

Kütüphane projemizin olduğu dizinde aşağıdaki içerikle tsconfig.json dosyası oluşturulur. Bu dosya Typescript derleyicisine(tsc) hangi dosyaları derlemesi gerektiğini, hangi söz dizimi(syntax) kontrolleri yapması gerektiği vb. belirtmektedir.

Kısaca bazı değerleri açıklayacak olursak:

• outDir: Derlenecek dosyaların hangi dizinde oluşturulacağını belirtir.
• target: ES5 standartına göre derleme işlemi yapar.
• declaration: Tür tanımlamalarının oluşturulması gerektiğini belirtir.
• exclude: TS derleyicisi bu klasördeki dosyalara bakmaz.
• include: TS derleyicisinin bakması gereken klasörleri belirtir.

Rollup konfigurasyonu için kütüphane projemizin olduğu dizinde rollup.config.js dosyası oluşturulur:

Burada ‘input’ parametresi ile kütüphanemizin dışarı çıkardığı (export) fonksiyon ve tanımlamaları belirten dosya yolunu veririz. Rollup bu dosyayı girdi olarak alır ve çıktı olarak iki dosya oluşturur. Bunlardan biri CommonJS formatında olan /lib/cjs/index.js dosyası diğeri ise ES formatında olan /lib/esm/index.js dosyasıdır.

external olarak belirtiğimiz değerler tam olarak kütüphane projemizin package.json dosyasında tanımlanan “peerDependencies” kısmıdır. Bu parametre ile rollup’a bunları paketlenmiş modüle eklememesi gerektiği söylenir çünkü kütüphane kullanıcısı bu paketleri kendisi yüklemektedir.

Rollup ile birlikte Typescript kullanımı için eklentilere 21.satırda Typescript eklenmektedir. (rollup-plugin-typescript2)

3.3. Kütüphane Projesinin Package.json Ayarları

Projemizi kütüphane olarak ayarlamak ve rollup’u otomatik olarak çalıştırmak için package.json dosyasında birkaç değişiklik yapmamız gerekir bunun için package.json dosyası aşağıdaki şekilde düzenlenir:

Burada;

• main: Kütüphanenin ana dosyasının yolunu belirtir.
• module: Kütüphanenin sunduğu ES modülünün yolunu belirtir.
• types: Kütüphanenin tür tanımlamalarının olduğu dosya yolunu belirtir.
• files: NPM’e hangi dizin veya dosyaların paketlenmesi gerektiğini söyler.

scripts altında yazılan komutların anlamı ise;

• rollup -c: Rollup’un paketleme işlemini yapması
• rollup -cw: Rollup’un paketleme işlemini yapması ve değişiklikleri izlemesi( değişiklik oldukça yeniden paketleme yapar. )

Burada tanımlanan komutların kök dizinde çalıştırılan yarn build ve yarn watch komutları ile çalışacağını unutmayalım. (Bkz. /package.json : lerna run build — scope react-ts-library)

Son olarak kullanacağımız 3.parti kütüphane olan Konva projeye eklenir. Bunun için kütüphane projemizin olduğu dizine giderek:

cd packages/react-ts-library
yarn add konva react-konva

4. Kütüphanenin Yazılması ve Derlenmesi

Uzun bir konfigurasyondan sonra artık kodlamaya geçebiliriz. İlk olarak kütüphane projesinin olduğu dizinde gerekli klasörler oluşturulur:

cd packages/react-ts-library
mkdir src/ lib/

Ardından src dizininde kütüphanemizin dışarı vermesi istediği tanımlamalar ve değerler için index.ts, fonksiyonelliği için React bileşeni oluşturulur.

src/index.ts dosyası;

React bileşeni için src/HelloLibrary.tsx;

4.1. Kütüphanenin Derlenmesi

Kütüphaneyi derlemek için kök dizinden hazırladığımız script’ler çağırılabilir:

yarn build

Bu komut ardından herhangi bir hata almadıysanız lib/ klasörü altında esm/ ve cjs/ dizinlerinin içindeki dosyaları inceleyebilirsiniz. Tebrikler başarılı bir şekilde React kütüphanesi geliştirdiniz. Geriye kütüphaneyi test etmek kaldı.

5. Örnek Projelerin Oluşturulması ve Kütüphanenin Kullanılması

Örnek projeleri oluşturmak için kök dizin içerisindeki examples/ klasörüne gidilir ardından burada TS ve JS ile iki adet React projesi oluşturulur.

yarn create react-app react-ts-example --template typescript
yarn create react-app react-js-example

Ardından projelere oluşturduğumuz kütüphane yüklenir bunun için kök dizinde:

lerna add react-ts-library --scope react-ts-example
lerna add react-ts-library --scope react-js-example

Kütüphanenin Kullanılması

Typescript kullanan React projesinin App.tsx dosyası aşağıdaki gibi değiştirilir:

Javascript kullanan React projesinin App.jsx dosyası aşağıdaki gibi değiştirilir:

Ardından projeler başlatılır:

yarn start

Değişimlerin İncelenmesi

Eğer rollup’un değişimleri inceleyip kodu tekrardan derlemesini ve kütüphane üzerinde çalışıp aynı zamanda örnek projelerimizde çalışmak istiyorsak bunun için kök dizinde oluşturduğumuz “watch” script’i çağırılır.

yarn watch

Bir yandan örnek projelerde çalışmak için projenin olduğu dizinden proje başlatılır:

yarn start

Böylelikle kütüphane veya projede herhangi bir yaptığımız değişiklik otomatik olarak uygulanacaktır.

Projenin Sıkıştırılmış Dosyasının Oluşturulması

Projenin sıkıştırılmış arşivi için kök dizinden aşağıdaki komut çalıştırılır:

yarn package

Daha ileride oluşturduğumuz bir projede kütüphaneyi kullanmak istersek aşağıdaki komut ile bu arşivden yüklenebilir:

npm install /dosya/yolu/react-ts-library.tgz

Kaynak Kodlar

Eğer tek tek konfigurasyon ile uğraşmak istemezseniz kodun hazır halini git üzerinden indirebilirsiniz.

git clone https://github.com/Spelchure/react-ts-library.git
lerna bootstrap
cd examples/react-ts-example
yarn start

Kaynak kod için tıklayınız.

Okuduğunuz için teşekkürler herhangi bir hata ve soru için iletişime geçmeyi ihmal etmeyin…