Kütüphane oluşturma

Bu sayfa, Angular işlevselliğini genişletmek için yeni kütüphanelerin nasıl oluşturulacağı ve yayınlanacağına dair kavramsal bir genel bakış sunar.

Birden fazla uygulamada aynı sorunu çözmeniz gerektiğini fark ederseniz (veya çözümünüzü diğer geliştiricilerle paylaşmak isterseniz), bir kütüphane adayınız var demektir. Basit bir örnek, kullanıcıları şirket web sitenize yönlendiren ve şirketinizin oluşturduğu tüm uygulamalarda yer alacak bir düğme olabilir.

Başlarken

Aşağıdaki komutlarla yeni bir çalışma alanında yeni bir kütüphane iskeleti oluşturmak için Angular CLI'yi kullanın.

ng new my-workspace --no-create-application
cd my-workspace
ng generate library my-lib

ng generate komutu, çalışma alanınızda bir bileşen içeren projects/my-lib klasörünü oluşturur.

Aynı çalışma alanını birden fazla proje için kullanmak üzere monorepo modelini kullanın. Bkz. Setting up for a multi-project workspace.

Yeni bir kütüphane oluşturduğunuzda, çalışma alanı yapılandırma dosyası angular.json, library türünde bir projeyle güncellenir.

"projects": {
  …
  "my-lib": {
    "root": "projects/my-lib",
    "sourceRoot": "projects/my-lib/src",
    "projectType": "library",
    "prefix": "lib",
    "architect": {
      "build": {
        "builder": "@angular/build:ng-packagr",
        …

CLI komutlarıyla projeyi derleyin, test edin ve lint yapın:

ng build my-lib --configuration development
ng test my-lib
ng lint my-lib

Proje için yapılandırılmış builder'ın, uygulama projeleri için varsayılan builder'dan farklı olduğuna dikkat edin. Bu builder, diğer şeylerin yanı sıra, kütüphanenin her zaman AOT derleyicisi ile derlenmesini sağlar.

Kütüphane kodunu yeniden kullanılabilir hale getirmek için bunun için bir genel API tanımlamalısınız. Bu "kullanıcı katmanı", kütüphanenizin tüketicilerine neyin sunulduğunu tanımlar. Kütüphanenizin bir kullanıcısı, genel işlevselliğe (servis sağlayıcıları ve genel yardımcı fonksiyonlar gibi) tek bir içe aktarma yolu aracılığıyla erişebilmelidir.

Kütüphanenizin genel API'si, kütüphane klasörünüzdeki public-api.ts dosyasında yönetilir. Bu dosyadan dışa aktarılan her şey, kütüphaneniz bir uygulamaya aktarıldığında herkese açık hale gelir.

Kütüphaneniz, kurulum ve bakım için belgeler (genellikle bir README dosyası) sağlamalıdır.

Bir uygulamanın bölümlerini kütüphaneye dönüştürme

Çözümünüzü yeniden kullanılabilir hale getirmek için, uygulamaya özel koda bağımlı olmayacak şekilde ayarlamanız gerekir. Uygulama işlevselliğini bir kütüphaneye taşırken dikkate alınması gereken bazı noktalar şunlardır.

• Bileşenler ve pipe'lar gibi bildirimler durumsuz olarak tasarlanmalıdır, yani harici değişkenlere bağlı olmamalı veya bunları değiştirmemelidir. Duruma bağlıysanız, her durumu değerlendirmeli ve bunun uygulama durumu mu yoksa kütüphanenin yöneteceği bir durum mu olduğuna karar vermelisiniz.

• Bileşenlerin dahili olarak abone olduğu tüm observable'lar, bu bileşenlerin yaşam döngüsü sırasında temizlenmeli ve elden çıkarılmalıdır

• Bileşenler etkileşimlerini, bağlam sağlamak için input'lar ve diğer bileşenlere olay iletmek için output'lar aracılığıyla açığa çıkarmalıdır

• Tüm dahili bağımlılıkları kontrol edin.

  • Bileşenlerde veya servislerde kullanılan özel sınıflar veya arayüzler için, bunların da taşınması gereken ek sınıflara veya arayüzlere bağlı olup olmadığını kontrol edin
  • Benzer şekilde, kütüphane kodunuz bir servise bağlıysa, o servisin de taşınması gerekir
  • Kütüphane kodunuz veya şablonları diğer kütüphanelere (örneğin Angular Material gibi) bağlıysa, kütüphanenizi bu bağımlılıklarla yapılandırmalısınız

• İstemci uygulamalarına servisleri nasıl sağladığınızı düşünün.

  • Servisler, NgModule veya bir bileşende sağlayıcı bildirmek yerine kendi sağlayıcılarını bildirmelidir. Bir sağlayıcı bildirmek, o servisi tree-shakable yapar. Bu uygulama, derleyicinin kütüphaneyi içe aktaran uygulamaya hiç enjekte edilmeyen servisi paket dışında bırakmasına olanak tanır. Bu konuda daha fazla bilgi için bkz. Tree-shakable providers.

  • Global servis sağlayıcıları kaydediyorsanız bir provideXYZ() sağlayıcı fonksiyonu sunun.

  • Kütüphaneniz tüm istemci uygulamaları tarafından kullanılmayabilecek isteğe bağlı servisler sağlıyorsa, bu durum için hafif token tasarım deseni kullanarak uygun tree-shaking desteği sağlayın

Kod oluşturma şematikleri kullanarak CLI ile entegrasyon

Bir kütüphane genellikle bir projeye aktardığınız bileşenler, servisler ve diğer Angular yapıtaşlarını (pipe'lar, direktifler) tanımlayan yeniden kullanılabilir kod içerir. Bir kütüphane, yayınlama ve paylaşım için bir npm paketine paketlenir. Bu paket ayrıca, CLI'nin ng generate component ile genel yeni bir bileşen oluşturmasıyla aynı şekilde, doğrudan projenizde kod oluşturmak veya dönüştürmek için talimatlar sağlayan şematikler de içerebilir. Bir kütüphaneyle paketlenmiş bir şematik, örneğin Angular CLI'ye, o kütüphanede tanımlanmış belirli bir özelliği veya özellik kümesini yapılandıran ve kullanan bir bileşen oluşturmak için gereken bilgileri sağlayabilir. Bunun bir örneği, CDK'nın BreakpointObserver'ını yapılandıran ve bunu Material'in MatSideNav ve MatToolbar bileşenleriyle kullanan Angular Material'in navigasyon şematiğidir.

Aşağıdaki türde şematikler oluşturun ve dahil edin:

• ng add'in kütüphanenizi bir projeye ekleyebilmesi için bir kurulum şematiği dahil edin
• ng generate'in tanımladığınız yapıtaşlarını (bileşenler, servisler, testler) bir projede iskele olarak oluşturabilmesi için kütüphanenize oluşturma şematikleri dahil edin
• ng update'in kütüphanenizin bağımlılıklarını güncelleyebilmesi ve yeni sürümlerdeki kırılma değişiklikleri için geçişler sağlayabilmesi için bir güncelleme şematiği dahil edin

Kütüphanenize neleri dahil edeceğiniz görevinize bağlıdır. Örneğin, bir uygulamaya nasıl ekleneceğini göstermek için önceden doldurulmuş verilerle bir açılır menü oluşturan bir şematik tanımlayabilirsiniz. Her seferinde farklı aktarılan değerler içerecek bir açılır menü istiyorsanız, kütüphaneniz belirli bir yapılandırmayla oluşturmak için bir şematik tanımlayabilir. Geliştiriciler daha sonra kendi uygulamaları için bir örnek yapılandırmak üzere ng generate komutunu kullanabilir.

Bir yapılandırma dosyasını okumak ve ardından bu yapılandırmaya dayalı bir form oluşturmak istediğinizi varsayalım. Bu form, kütüphanenizi kullanan geliştirici tarafından ek özelleştirme gerektiriyorsa, bir şematik olarak en iyi şekilde çalışabilir. Ancak form her zaman aynı olacak ve geliştiriciler tarafından fazla özelleştirme gerektirmeyecekse, yapılandırmayı alan ve formu oluşturan dinamik bir bileşen oluşturabilirsiniz. Genel olarak, özelleştirme ne kadar karmaşıksa, şematik yaklaşımı o kadar kullanışlıdır.

Daha fazla bilgi için bkz. Schematics Overview ve Schematics for Libraries.

Kütüphanenizi yayınlama

Kütüphanenizi bir npm paketi olarak derlemek ve yayınlamak için Angular CLI'yi ve npm paket yöneticisini kullanın.

Angular CLI, derlenmiş kodunuzdan npm'e yayınlanabilecek paketler oluşturmak için ng-packagr adlı bir araç kullanır. ng-packagr tarafından desteklenen dağıtım formatları ve kütüphaneniz için doğru formatı seçme konusunda rehberlik için bkz. Building libraries with Ivy.

Dağıtım için kütüphaneleri her zaman production yapılandırmasını kullanarak derlemelisiniz. Bu, oluşturulan çıktının uygun optimizasyonları ve npm için doğru paket formatını kullanmasını sağlar.

ng build my-lib
cd dist/my-lib
npm publish

Bir kütüphanedeki varlıkları yönetme

Angular kütüphanenizde, dağıtılabilir paket tema dosyaları, Sass mixin'leri veya belgeler (değişiklik günlüğü gibi) gibi ek varlıklar içerebilir. Daha fazla bilgi için varlıkları derlemenin bir parçası olarak kütüphanenize kopyalama ve varlıkları bileşen stillerine gömme konularına bakın.

ng-packagr, elle yazılmış "exports" ile otomatik oluşturulanları birleştirir ve kütüphane yazarlarının ek dışa aktarma alt yolları veya özel koşullar yapılandırmasına olanak tanır.

"exports": {
  ".": {
    "sass": "./_index.scss",
  },
  "./theming": {
    "sass": "./_theming.scss"
  },
  "./prebuilt-themes/indigo-pink.css": {
    "style": "./prebuilt-themes/indigo-pink.css"
  }
}

Yukarıdaki, @angular/material dağıtılabilir paketinden bir alıntıdır.

Eş bağımlılıklar

Angular kütüphaneleri, kütüphanenin bağımlı olduğu tüm @angular/* bağımlılıklarını eş bağımlılıklar olarak listelemelidir. Bu, modüller Angular istediğinde hepsinin tam olarak aynı modülü almasını sağlar. Bir kütüphane @angular/core'u peerDependencies yerine dependencies'te listelerse, farklı bir Angular modülü alabilir ve bu da uygulamanızın bozulmasına neden olabilir.

Kendi kütüphanenizi uygulamalarda kullanma

Kütüphanenizi aynı çalışma alanında kullanmak için npm paket yöneticisine yayınlamanız gerekmez, ancak önce derlemeniz gerekir.

Kendi kütüphanenizi bir uygulamada kullanmak için:

• Kütüphaneyi derleyin. Derlenmeden önce bir kütüphaneyi kullanamazsınız.

  ng build my-lib

• Uygulamalarınızda kütüphaneden ada göre içe aktarın:

import {myExport} from 'my-lib';

Kütüphanenizi derleme ve yeniden derleme

Kütüphanenizi npm paketi olarak yayınlamadıysanız ve ardından paketi npm'den uygulamanıza geri yüklemediyseniz derleme adımı önemlidir. Örneğin, git deponuzu klonlayıp npm install çalıştırırsanız, kütüphanenizi henüz derlemediyseniz editörünüz my-lib içe aktarımlarını eksik olarak gösterir.

Angular CLI ile bir kütüphane oluşturmak, yolunu otomatik olarak tsconfig dosyasına ekler. Angular CLI, derleme sistemine kütüphaneyi nerede bulacağını söylemek için tsconfig yollarını kullanır.

Daha fazla bilgi için bkz. Path mapping overview.

Kütüphanenizde her değişiklik yaptığınızda yeniden derleyebilirsiniz, ancak bu ek adım zaman alır. Artımlı derleme işlevselliği kütüphane geliştirme deneyimini iyileştirir. Bir dosya her değiştirildiğinde, değiştirilen dosyaları yayan kısmi bir derleme gerçekleştirilir.

Artımlı derlemeler, geliştirme ortamınızda arka plan işlemi olarak çalıştırılabilir. Bu özellikten yararlanmak için derleme komutuna --watch bayrağını ekleyin:

ng build my-lib --watch

• Uygulamalar için derleme sistemi @angular/build, esbuild tabanlıdır ve tüm yeni Angular CLI projelerine dahildir
• Kütüphaneler için derleme sistemi ng-packagr tabanlıdır. Yalnızca ng generate library my-lib kullanarak bir kütüphane eklediğinizde bağımlılıklarınıza eklenir.

İki derleme sistemi farklı şeyleri destekler ve aynı şeyleri desteklediklerinde bile bunları farklı şekilde yaparlar. Bu, TypeScript kaynağının derlenmiş bir kütüphanede, derlenmiş bir uygulamadakinden farklı JavaScript koduna dönüşebileceği anlamına gelir.

Bu nedenle, bir kütüphaneye bağımlı olan bir uygulama yalnızca derlenmiş kütüphaneye işaret eden TypeScript yol eşlemelerini kullanmalıdır. TypeScript yol eşlemeleri kütüphane kaynağı .ts dosyalarına işaret etmemelidir.

Yerel geliştirme için kütüphaneleri bağlama

Bu bölüm, monorepo çalışma alanı yapısına veya npm kayıt defterine yayınlamaya bağlı kalmadan, yerel geliştirme sırasında bağımsız bir Angular kütüphanesini harici bir uygulama ile test etmek için paket yöneticinizin yerel bağlama özelliğini (npm link veya pnpm link gibi) nasıl kullanacağınızı açıklar.

• Bağımsız bir kütüphane geliştiriyorsunuz ve değişiklikleri harici, tüketen bir uygulama ile test etmeniz gerekiyor.
• Kütüphane değişikliklerini monorepo çalışma alanı dışındaki tüketen bir uygulamada test ediyorsunuz.

Tüketen uygulamayı yapılandırma

Bağlanmış kütüphaneleri kullanmak için uygulamanızın angular.json dosyasını aşağıdaki ayarlarla yapılandırmanız gerekir:

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "preserveSymlinks": true
          },
          "configurations": {
            "development": {
              "sourceMap": {
                "scripts": true,
                "styles": true,
                "vendor": true
              }
            }
          }
        },
        "serve": {
          "builder": "@angular/build:dev-server",
          "options": {
            "prebundle": {
              "exclude": ["my-lib"]
            }
          }
        }
      }
    }
  }
}

Yapılandırma seçeneklerinin açıklaması:

• preserveSymlinks: true: Derleme sistemine, sembolik bağlantının orijinal konumuna çözümlemek yerine paket yöneticinizin bağlama komutuyla oluşturulan sembolik bağlantıları takip etmesini söyler. Bu, bağımlı node paketlerinin birden fazla kopyasını önlemek için gereklidir.
• sourceMap.vendor: Bağlanmış kütüphane kodunun daha kolay hata ayıklaması için satıcı kaynak haritalarını etkinleştirme (özellikle vendor: true).
• prebundle.exclude: Varsayılan olarak, Angular CLI tüm node bağımlılıklarını önceden paketleyebilir. Kütüphanenizi hariç tutmak, bağlanmış kaynak kodunun düzgün şekilde izlenmesini ve değişiklikler olduğunda yeniden derlenmesini sağlar.

Kütüphaneleri yayınlama

Bir kütüphaneyi yayınlarken kullanılacak iki dağıtım formatı vardır:

npm'e yayınlamak için, Angular'ın yama sürümleri arasında kararlı olduğu için partial-Ivy formatını kullanın.

Oluşturulan Ivy talimatları Angular'ın genel API'sinin bir parçası olmadığından ve yama sürümleri arasında değişebileceğinden, npm'e yayınlıyorsanız kütüphaneleri full-Ivy koduyla derlemeyin.

Kütüphane sürüm uyumluluğunu sağlama

Bir uygulamayı derlemek için kullanılan Angular sürümü her zaman, bağımlı kütüphanelerinin herhangi birini derlemek için kullanılan Angular sürümleriyle aynı veya daha yüksek olmalıdır. Örneğin, Angular sürüm 13 kullanan bir kütüphaneniz varsa, o kütüphaneye bağımlı olan uygulama Angular sürüm 13 veya üstünü kullanmalıdır. Angular, uygulama için daha eski bir sürüm kullanmayı desteklemez.

Kütüphanenizi npm'e yayınlamak istiyorsanız, tsconfig.prod.json'da "compilationMode": "partial" ayarlayarak partial-Ivy koduyla derleyin. Bu kısmi format, Angular'ın farklı sürümleri arasında kararlıdır, bu nedenle npm'e yayınlamak güvenlidir. Bu formattaki kod, uygulama derlemesi sırasında Angular derleyicisinin aynı sürümü kullanılarak işlenir ve uygulamanın ve tüm kütüphanelerinin tek bir Angular sürümü kullanmasını sağlar.

Oluşturulan Ivy talimatları Angular'ın genel API'sinin bir parçası olmadığından ve yama sürümleri arasında değişebileceğinden, npm'e yayınlıyorsanız kütüphaneleri full-Ivy koduyla derlemeyin.

npm'de daha önce hiç paket yayınlamadıysanız, bir kullanıcı hesabı oluşturmanız gerekir. Daha fazla bilgi için bkz. Publishing npm Packages.

Angular CLI dışında partial-Ivy kodunu kullanma

Bir uygulama, node_modules dizinine npm'den birçok Angular kütüphanesi yükler. Ancak bu kütüphanelerdeki kod, tam olarak derlenmediği için doğrudan derlenmiş uygulamayla birlikte paketlenemez. Derlemeyi tamamlamak için Angular bağlayıcısını kullanın.

Angular CLI kullanmayan uygulamalar için bağlayıcı, bir Babel eklentisi olarak mevcuttur. Eklenti, @angular/compiler-cli/linker/babel'den içe aktarılır.

Angular bağlayıcı Babel eklentisi derleme önbelleklemeyi destekler, yani kütüphanelerin diğer npm işlemlerinden bağımsız olarak bağlayıcı tarafından yalnızca bir kez işlenmesi gerekir.

Bağlayıcıyı, babel-loader kullanarak Babel eklentisi olarak kaydederek özel bir webpack derlemesine entegre etme örneği.

import linkerPlugin from '@angular/compiler-cli/linker/babel';

export default {
  // ...
  module: {
    rules: [
      {
        test: /\.m?js$/,
        use: {
          loader: 'babel-loader',
          options: {
            plugins: [linkerPlugin],
            compact: false,
            cacheDirectory: true,
          },
        },
      },
    ],
  },
  // ...
};