TypeScript paths ile Import Alias: baseUrl, rootDir ve outDir

paths nasıl tanımlanır?

paths, compilerOptions içinde bir nesnedir. Anahtar, importta yazacağınız kalıp; değer ise denenecek dosya yollarının dizisidir. baseUrl yoksa yollar tsconfig dosyasının bulunduğu klasöre göre çözülür.

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@config": ["./src/config/index.ts"]
    }
  }
}

Kalıpta yalnızca bir tane * joker karakteri bulunabilir ve eşleşen kısım değerdeki * yerine konur. "@/components/Button" importu için *, components/Button olur ve derleyici ./src/components/Button yolunu normal göreli yol kurallarıyla arar. Birden fazla kalıp eşleşirse * işaretinden önceki ön eki en uzun olan kalıp kazanır. Dizide birden fazla yol verirseniz ilki bulunamadığında sıradaki denenir; dokümantasyon buna fallback diyor.

tsc import yollarını yeniden yazmaz

Dokümantasyon bu konuda açık: paths çıktıdaki import yolunu değiştirmez; bu ayar yalnızca TypeScript'e "bu eşlemeyi çalışma anında ya da paketleme sırasında başka bir araç uygulayacak" bilgisini vermek için kullanılmalıdır. Bunu küçük bir Node.js projesiyle denedik. package.json dosyasında "type": "module" var:

{
  "compilerOptions": {
    "module": "nodenext",
    "rootDir": "./src",
    "outDir": "./dist",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src"]
}

// src/lib/selam.ts
export function selam(ad: string): string {
  return `Merhaba ${ad}`;
}

// src/index.ts
import { selam } from "@/lib/selam.js";
console.log(selam("dünya"));

npx tsc hatasız tamamlandı. Ancak dist/index.js dosyasında import satırı kaynaktaki gibi kaldı ve Node.js bu yolu tanımadı:

npx tsc
node dist/index.js
# Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/lib' imported from ...\dist\index.js

Node.js, @/lib ifadesini bir npm paketi adı gibi yorumladı. Dokümantasyon tam olarak bu durumu örnekliyor: TypeScript'te sorunsuz görünen bir alias çalışma anında çökebilir. Paketleyici kullanan uygulamalarda alias'ı paketleyici yapılandırmasında tanımlayıp TypeScript'e paths ile bildirmek yaygın bir yöntemdir; bu kurulumda "moduleResolution": "bundler" kullanılır. Yayımlanan kütüphaneler ise paths kullanmamalıdır, çünkü üretilen JavaScript, kullanıcı aynı alias'ları kendi ortamında tanımlamadıkça çalışmaz.

TypeScript 5.7 ile gelen rewriteRelativeImportExtensions seçeneği de burada yardımcı olmaz. Sürüm notlarına göre yalnızca ./ ya da ../ ile başlayan göreli yollardaki .ts uzantısını .js yapar; paths üzerinden çözülen @/ gibi yollara dokunmaz.

Node.js için çözüm: package.json "imports"

Dokümantasyonun hem uygulamalar hem kütüphaneler için önerdiği standart alternatif, package.json içindeki "imports" alanıdır. Bu alanı Node.js kendisi okur, dolayısıyla eşleme çalışma anında da geçerlidir. Aynı projede paths ayarını sildik ve package.json dosyasını şöyle düzenledik:

{
  "name": "ornek",
  "type": "module",
  "imports": {
    "#app/*": "./dist/*"
  }
}

// src/index.ts
import { selam } from "#app/lib/selam.js";
console.log(selam("dünya")); // Merhaba dünya

Eşleme derlenmiş dosyaları (./dist/*) gösteriyor, ama TypeScript tip denetimi sırasında kaynak dosyaları kullanmak ister. Modül referansına göre derleyici, yerel projedeki bir "imports" hedefinde outDir ön ekini rootDir ile değiştirip .ts karşılığını arar; bu yüzden "imports" kullanırken rootDir değerini açıkça yazmanız gerekir. npx tsc ardından node dist/index.js çalıştırdığımızda çıktı Merhaba dünya oldu.

TypeScript 6.0, Node.js'in yeni eklediği #/ önekini de nodenext ve bundler modlarında destekliyor; sürüm notları bu desteğin yeni Node.js sürümlerinde geldiğini belirtiyor. Denememizde "#/*" anahtarını tsc kabul etti, ancak Node.js 24.4.0 çıktıyı ERR_INVALID_MODULE_SPECIFIER hatasıyla reddetti. #/ kullanmadan önce Node.js sürümünüzün bu biçimi desteklediğini doğrulayın; emin değilseniz #app/ gibi bir ek kullanın.

TypeScript 6.0'da baseUrl kullanımdan kaldırıldı

baseUrl eskiden paths değerlerine ön ek vermek için kullanılırdı, ama aynı zamanda tüm göreli olmayan importlar için bir arama kökü işlevi görüyordu. Sürüm notlarına göre bu durum, çalışma anında hiç çalışmayacak birçok import yolunun TypeScript tarafından geçerli sayılmasına yol açıyordu. TypeScript 4.1'den beri paths için baseUrl zaten gerekmiyor. 6.0 ile baseUrl kullanımdan kaldırıldı ve artık arama kökü olarak değerlendirilmiyor. Ayarı bıraktığımızda derleyici şu hatayı verdi:

error TS5101: Option 'baseUrl' is deprecated and will stop functioning in TypeScript 7.0. Specify compilerOption '"ignoreDeprecations": "6.0"' to silence this error.

Geçiş çoğu projede basittir: baseUrl satırını silip önekini her paths değerine eklersiniz.

// Önce
{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": { "@app/*": ["app/*"], "@lib/*": ["lib/*"] }
  }
}

// Sonra
{
  "compilerOptions": {
    "paths": { "@app/*": ["./src/app/*"], "@lib/*": ["./src/lib/*"] }
  }
}

baseUrl değerini gerçekten arama kökü olarak kullanan projeler, "*": ["./src/*"] biçiminde genel bir eşleme ekleyerek eski davranışı koruyabilir; sürüm notları bunun çok nadir olduğunu ve çoğu proje için önerilen yolun ön eki paths değerlerine taşımak olduğunu söylüyor. Ekip, baseUrl ve rootDir düzenlemelerini otomatik yapan deneysel bir ts5to6 aracından da söz ediyor.

rootDir ve outDir: çıktı klasörü nasıl oluşur?

outDir, .js, .d.ts ve kaynak haritası dosyalarının yazılacağı klasördür. Verilmezse her .js dosyası kaynağının yanına yazılır. rootDir ise kaynak ağacının hangi klasörden itibaren outDir içine kopyalanacağını belirler. TypeScript 6.0 öncesinde rootDir verilmezse tüm kaynak dosyaların ortak üst klasörü hesaplanıyordu. 6.0 ile varsayılan, tsconfig dosyasının bulunduğu klasör oldu; hesaplama yalnızca tsconfig olmadan komut satırından derlerken yapılıyor.

Bu değişikliğin pratik etkisini ilk denememizde gördük. rootDir yazmadan derlediğimizde dosyalar dist/src/index.js konumuna yazıldı ve derleyici şu hatayı verdi:

tsconfig.json(4,5): error TS5011: The common source directory of 'tsconfig.json' is './src'. The 'rootDir' setting must be explicitly set to this or another path to adjust your output's file layout.
  Visit https://aka.ms/ts6 for migration information.

"rootDir": "./src" ekledikten sonra çıktılar beklenen yere, dist/index.js ve dist/lib/selam.js konumlarına yazıldı. Sürüm notları da ./dist/index.js yerine ./dist/src/index.js görüyorsanız sebebin bu olduğunu belirtiyor.

rootDir derlemeye hangi dosyaların gireceğini değiştirmez; bunu include, exclude ve files belirler. Ama derlenen her dosyanın rootDir altında olması gerekir, çünkü TypeScript outDir dışına dosya yazmaz. src dışındaki bir dosyayı import ettiğimizde TS6059 hatasını aldık: File '...' is not under 'rootDir' '.../src'. 'rootDir' is expected to contain all source files.

paths kullanırken dikkat edilecekler

• node_modules paketlerini ya da monorepo içindeki paketleri paths ile göstermeyin. Alias çözüldükten sonra yol göreli yol gibi işlenir; paketin exports, types ve main alanları devre dışı kalır. Monorepo için dokümantasyon npm, yarn veya pnpm workspace kullanmayı öneriyor.
• Paketleyicideki alias ile tsconfig'deki paths eşlemesini aynı tutun. İkisi ayrıştığında TypeScript bir dosyayı bulurken paketleyici başka bir dosyayı yükleyebilir.
• Yayımladığınız kütüphanede paths kullanmayın. Paket içi kısa yollar için "imports" alanını tercih edin.
• 6.0'a geçerken baseUrl satırını kaldırın ve öneki paths değerlerine taşıyın; ignoreDeprecations yalnızca geçici bir çözüm.

Sık Sorulan Sorular

tsc neden @/ ile başlayan importları çıktıda göreli yola çevirmiyor?

Çünkü paths tasarım gereği yalnızca tip denetimi ve modül çözümleme için kullanılır; dokümantasyon bu ayarın çıktıdaki import yollarını değiştirmediğini açıkça yazıyor. Dönüşüm gerekiyorsa paketleyici kullanın ya da Node.js'in okuduğu package.json "imports" alanına geçin.

TypeScript 6.0'da baseUrl kullanmaya devam edebilir miyim?

"ignoreDeprecations": "6.0" ile 6.0'da çalışır, ama artık arama kökü olarak değerlendirilmez ve TypeScript 7.0 bu seçeneği desteklemeyecek. Öneki paths değerlerine taşımak en temiz çözümdür.

Çıktılar neden dist/src klasörüne yazılıyor?

6.0'da rootDir varsayılanı tsconfig klasörü olduğu için src klasörü de çıktı ağacına giriyor. "rootDir": "./src" yazarak dosyaları doğrudan dist altına alabilirsiniz.

paths mi, package.json imports mu kullanmalıyım?

Kod paketleyiciden geçiyorsa ve alias paketleyicide tanımlıysa paths yeterlidir. Kodu tsc ile derleyip doğrudan Node.js ile çalıştırıyorsanız ya da kütüphane yayımlıyorsanız "imports" alanı hem TypeScript hem çalışma anı tarafından anlaşılır.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: TypeScript öğrenme rehberi · tsconfig.json rehberi · TypeScript modül çözümleme · project references · TypeScript ile Node.js · JavaScript ES modülleri