KickJS ile Dosya Çözümlemeyi Tür Güvenli Hale Getirin: Geliştirme ve Dağıtımdan Verimlilik

Geliştiriciler, Node.js uygulamalarında kaynak kod dışındaki dosyalara erişim sağlarken genellikle beklenmedik hatalara yol açan bir dizi zorlukla karşılaşır. E-posta şablonları, JSON şemaları veya satıcı PDF'leri gibi statik varlıkların yönetimi, geliştirme ortamıyla üretim ortamı arasındaki yol farklılıklarından dolayı karmaşık hale gelebilir. Bu sorunları ortadan kaldırmak için KickJS Asset Manager, projenizin derleme aşamasında varlıklarınızın konumlarını standartlaştırarak hem geliştirme hem de üretim sürecinde tutarlı bir dosya çözümleme sistemi sunar.

Geliştirme ve Üretim Ortamlarındaki Yol Farklılıkları

Node.js projelerinde karşılaşılan en yaygın sorunlardan biri, geliştirme (src/) ve üretim (dist/) ortamları arasındaki yol farklılıklarıdır. Örneğin, __dirname değişkeni geliştirme ortamında src/handlers/ klasörünü işaret ederken, üretim ortamında derlenmiş kodun bulunduğu dist/handlers/ klasörünü işaret edebilir. Bu durumda, göreceli yollar kullanıldığında kaynaklara erişim başarısız olur. KickJS Asset Manager, bu sorunu çözmek için varlıklarınızın konumlarını derleme aşamasında standartlaştırır ve üretim ortamında da aynı yapıyı korumanızı sağlar.

Var olan geçici çözümler genellikle process.env.NODE_ENV === 'production' ? '../../dist/templates' : '../templates' gibi ortam kontrollerine dayanır. Ancak bu yaklaşım, kod tabanınızda tutarsızlıklara ve bakım zorluklarına yol açar. KickJS Asset Manager ise bu sorunu, varlık yönetimini derleme zamanında ele alarak ortadan kaldırır.

Tür Güvenliği ve Manifest Yönetimi

KickJS Asset Manager, projenizin varlıklarını yönetmek için iki ana bileşen kullanır: bir manifest dosyası ve tür güvenli bir proxy. Bu bileşenler, geliştirme sürecini hem daha güvenilir hem de daha verimli hale getirir.

Manifest Dosyası: .kickjs-assets.json

Derleme aşamasında, KickJS Asset Manager tüm varlıklarınızı dist/ klasörüne kopyalar ve bu varlıkların konumlarını .kickjs-assets.json adlı bir manifest dosyasında kaydeder. Bu manifest dosyası, her bir varlık için kategori ve tanımlayıcı bilgilerini içerir. Örneğin, mails.welcome adlı bir e-posta şablonu için manifest şu şekilde görünebilir:

{
  "mails": {
    "welcome": "dist/assets/mails/welcome.ejs"
  }
}

Manifest dosyası, üretim ortamında çalışırken bile varlıklarınıza doğru şekilde erişmenizi sağlar.

Tür Güvenli Proxy: assets.d.ts

KickJS ayrıca, manifest dosyasındaki yapıya dayalı olarak otomatik olarak oluşturulan bir tür bildirimi olan .kickjs/types/assets.d.ts dosyasını da kullanır. Bu dosya, KickAssets adlı bir arayüz oluşturur ve bu arayüz, manifestteki her bir varlık için bir özellik içerir. Örneğin, mails.welcome adlı varlık için KickAssets['mails']['welcome'] adlı bir özellik oluşturulur.

Bu tür bildirimi sayesinde, geliştiriciler IDE'lerinde otomatik tamamlama ve hata denetimi kullanabilir. Yanlış bir varlık adını kullanmanız durumunda derleme aşamasında hata alırsınız, bu da çalışma zamanında karşılaşabileceğiniz sorunları önler.

Dört Farklı Varlık Tüketim Yöntemi

KickJS, varlıklarınıza erişmek için dört farklı yöntem sunar. Bu yöntemler, geliştirme stilinize ve projenizin ihtiyaçlarına göre seçilebilir.

1. Ortam Değişkeni Proxy: assets

En yaygın kullanılan yöntem, projenizin herhangi bir yerinden erişilebilen bir proxy kullanmaktır. Bu proxy, manifestte tanımlanan yapıya göre otomatik olarak oluşturulur ve IDE'lerde otomatik tamamlama özelliği sunar.

import { assets } from '@forinda/kickjs';

const path = assets.mails.welcome();
const html = await renderEjs(await readFile(path, 'utf8'), { user });

Bu yöntem, geliştiricilerin projelerindeki varlıkları kolayca bulmalarını ve kullanmalarını sağlar.

2. Hook Fabrikası: useAssets()

Bazen, varlık çözümleyicisini bir singleton olarak değil, bir fabrika fonksiyonu olarak kullanmak daha uygun olabilir. useAssets() fonksiyonu, aynı proxyyi bir fabrika olarak döndürür ve bu sayede testlerde veya bağımlılık enjeksiyonunda kullanılabilir.

import { useAssets } from '@forinda/kickjs';

class MailService {
  constructor(private readonly assets = useAssets()) {}

  async welcome() {
    return this.assets.mails.welcome();
  }
}

Bu yöntem, özellikle bağımlılık enjeksiyonunu tercih eden projelerde kullanışlıdır.

3. Sınıf Alanı Dekoratörü: @Asset()

Sınıf tabanlı projelerde, varlık çözümlemesini tembel yükleme ve bildirimsel bir şekilde gerçekleştirmek için @Asset() dekoratörü kullanılabilir. Bu dekoratör, sınıf alanınız için bir getter oluşturur ve ilk erişimde varlığı çözer.

import { Asset } from '@forinda/kickjs';

class MailService {
  @Asset('mails/welcome')
  private welcomeTpl!: string;

  async send(user: User) {
    const html = await renderEjs(await readFile(this.welcomeTpl, 'utf8'), { user });
  }
}

Bu yöntem, sınıf alanlarınızın temiz ve okunabilir kalmasını sağlar.

4. Dinamik Çözümleme: resolveAsset()

Bazı durumlarda, varlık adları çalışma zamanında dinamik olarak belirlenebilir. Bu gibi durumlarda, resolveAsset() fonksiyonu kullanılarak varlıklar dinamik olarak çözümlenebilir.

import { resolveAsset } from '@forinda/kickjs';

const path = resolveAsset('mails', slug);

Bu yöntem, varlık adlarının dinamik olarak değiştiği durumlarda kullanışlıdır, ancak tür güvenliği bu durumda sınırlıdır.

Derleme ve Üretim Sürecindeki Adımlar

KickJS Asset Manager, varlık yönetimini derleme ve üretim süreci arasında sorunsuz bir şekilde entegre eder. Projenizin yapılandırmasına bağlı olarak, kick build veya kick build:assets komutları kullanılarak varlıklarınız derlenir ve manifest dosyası oluşturulur.

Yapılandırma Dosyası: kick.config.ts

KickJS, projelerinizin yapılandırmasını kick.config.ts adlı bir dosyada yönetir. Bu dosya, hangi varlıkların derleneceğini ve nereye kopyalanacağını belirler. Örneğin:

import { defineConfig } from 'kickjs';

export default defineConfig({
  assetMap: [
    {
      src: 'src/assets/mails/**/*',
      dest: 'mails',
    },
  ],
});

Bu yapılandırma, KickJS'in src/assets/mails/ klasöründeki tüm dosyaları dist/assets/mails/ klasörüne kopyalamasını ve manifest dosyasında kaydetmesini sağlar.

KickJS Asset Manager, Node.js projelerinde varlık yönetimini basitleştirerek geliştirme sürecini daha güvenilir ve verimli hale getirir. Tür güvenliği ve otomatik manifest yönetimi sayesinde, hem geliştiriciler hem de kullanıcılar için daha sorunsuz bir deneyim sunar.