TypeScript Declaration Files: .d.ts Dosyası Nedir, Nasıl Yazılır?

.ts ile .d.ts arasındaki fark

Type Declarations belgesine göre .ts dosyaları hem tip hem çalışan kod içerir ve .js çıktısı üretir. .d.ts dosyaları yalnızca tip içerir ve sadece tip denetiminde kullanılır. Math.max veya Array.prototype.map gibi yerleşik API'lerin tipleri de TypeScript ile gelen lib.[ad].d.ts dosyalarından okunur; hangilerinin yükleneceğini target ve lib ayarları belirler (ayrıntılar target ve lib yazısında).

Modules Theory belgesi önemli bir varsayımı vurgular: derleyici bir bildirim dosyası gördüğünde, yanında bu bildirimle birebir uyumlu bir JavaScript dosyası olduğunu varsayar. Bu yüzden elle yazılan bildirimin adı ve uzantısı JavaScript dosyasıyla eşleşmelidir.

declaration: true ile otomatik üretmek

Kendi kodunuzu bir paket olarak yayınlayacaksanız tipleri elle yazmanıza gerek yok. tsconfig içinde declaration seçeneğini açın:

{
  "compilerOptions": {
    "module": "nodenext",
    "rootDir": "./src",
    "outDir": "./dist",
    "declaration": true
  },
  "include": ["src"]
}

// src/index.ts
export interface Fiyat {
  tutar: number;
  paraBirimi: "TRY" | "USD" | "EUR";
}

const KDV = 0.2;

export function kdvEkle(f: Fiyat): Fiyat {
  return { ...f, tutar: Math.round(f.tutar * (1 + KDV) * 100) / 100 };
}

export class Sepet {
  #kalemler: Fiyat[] = [];
  ekle(f: Fiyat) {
    this.#kalemler.push(f);
    return this;
  }
  get adet() {
    return this.#kalemler.length;
  }
}

tsc -p . çalıştırınca dist klasöründe index.js ile birlikte şu index.d.ts oluştu:

export interface Fiyat {
    tutar: number;
    paraBirimi: "TRY" | "USD" | "EUR";
}
export declare function kdvEkle(f: Fiyat): Fiyat;
export declare class Sepet {
    #private;
    ekle(f: Fiyat): this;
    get adet(): number;
}

Dikkat edilecek üç nokta var: dışa aktarılmayan KDV sabiti bildirime girmedi; fonksiyon gövdeleri yerine yalnızca imzalar kaldı; #kalemler alanının adı ve tipi yerine sadece #private; yazıldı. Bildirim dosyası paketin dışarıya açık yüzünü (API) anlatır. declarationMap açarsanız editördeki "Go to Definition" komutu .d.ts yerine kaynak koda gider.

Yayın Publishing belgesine göre package.json içindeki types alanı ana bildirim dosyasını göstermelidir:

{
  "name": "fiyat-araclari",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts"
}

Bir JavaScript dosyası için elle .d.ts yazmak

Projenizde tipi olmayan eski bir JavaScript modülü olduğunu düşünelim. "module": "nodenext" ve strict açıkken onu import ettiğimizde derleyici örtük any kabul etmedi (dosya yolunu kısalttık):

// src/slug.js
export function slugYap(metin, ayrac = "-") {
  return metin.toLowerCase().trim().replace(/\s+/g, ayrac);
}
export const SURUM = "1.2.0";

// src/main.ts
import { slugYap, SURUM } from "./slug.js";
// TS7016: Could not find a declaration file for module './slug.js'.
// '.../src/slug.js' implicitly has an 'any' type.

Çözüm, JavaScript dosyasıyla aynı adda bir slug.d.ts eklemektir. Bildirimde declare anahtar kelimesi gövdesiz tanım yaptığınızı belirtir; isteğe bağlı parametreyi ? ile işaretlersiniz:

// src/slug.d.ts
/** Metni küçük harfe çevirip boşlukları ayraçla değiştirir. */
export declare function slugYap(metin: string, ayrac?: string): string;
export declare const SURUM: string;

// src/main.ts
import { slugYap, SURUM } from "./slug.js";

console.log(slugYap("Merhaba Dünya")); // merhaba-dünya
console.log(SURUM);                   // 1.2.0

slugYap(42);
// TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

Artık JavaScript fonksiyonu da tip denetiminden geçiyor ve JSDoc yorumu editörde görünüyor. Fonksiyon aşırı yüklemesi (overload), sınıf, global değişken ve namespace bildirimlerinin kalıpları için resmî Declaration Reference sayfasına bakabilirsiniz. Overload yazımı fonksiyon tipleri yazısında da var.

Tipi olmayan paketler: declare module

node_modules içindeki bir paketin ne kendi tipi ne de bir @types paketi varsa yine TS7016 alırsınız. Projeye bir .d.ts dosyası ekleyip paketi declare module ile tanımlayabilirsiniz. Aynı dosyada derleme aracınızın eklediği global bir sabiti de bildirebilirsiniz:

// src/tipler.d.ts
declare module "renkli" {
  export function kirmizi(metin: string): string;
}

declare const UYGULAMA_SURUMU: string;

// src/main.ts
import { kirmizi } from "renkli";
console.log(kirmizi("hata"));
console.log(UYGULAMA_SURUMU.toUpperCase());

kirmizi(5);
// TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

Bildirim dosyası olmadan aynı kod UYGULAMA_SURUMU için TS2304: Cannot find name 'UYGULAMA_SURUMU'. hatası verdi. Hızlı bir geçiş için yalnızca declare module "renkli"; yazmak da mümkündür; Type Declarations belgesine göre bu kısa biçimde modüldeki her şey any olur, yani tip güvenliğinden vazgeçersiniz. any ile unknown farkı için any, unknown ve never yazısına bakın.

@types paketleri ve TypeScript 6.0'daki types değişikliği

DefinitelyTyped deposundaki bildirimler npm'e @types kapsamında yayınlanır ve paket adı asıl paketle aynıdır. Örneğin lodash için:

npm install --save-dev @types/lodash

Paket kendi bildirimini zaten içeriyorsa ayrıca @types kurmanıza gerek yoktur. Import ettiğiniz paketlerin tipleri her zaman bulunur. Değişen şey, process veya test çatılarının describe gibi global tanımlarıdır. TypeScript 6.0 sürüm notlarına göre types seçeneğinin varsayılanı artık []; yani node_modules/@types altındaki paketler global olarak otomatik yüklenmiyor. @types/node yüklü olmayan projemizde şu hatayı aldık:

console.log(process.env.PORT);
// TS2591: Cannot find name 'process'. Do you need to install type definitions for node?
// Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

{
  "compilerOptions": {
    "types": ["node"]
  }
}

Sürüm notları "types": ["*"] yazarak 5.9 davranışına dönülebileceğini, ancak derleme performansı için açık bir liste önerdiğini belirtir.

JavaScript projesinden .d.ts üretmek

Projeniz JavaScript olarak kalacaksa bile JSDoc yorumlarından bildirim üretebilirsiniz. Resmî "Creating .d.ts Files from .js files" sayfasındaki ayarın özü şudur: allowJs JavaScript dosyalarını okutur, declaration bildirim üretir, emitDeclarationOnly JavaScript dosyalarının üzerine yazılmasını engeller:

{
  "include": ["src/**/*"],
  "compilerOptions": {
    "allowJs": true,
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "dist",
    "declarationMap": true
  }
}

Sık yapılan hatalar

• Bildirimde String, Number, Boolean veya Object kullanmak. Do's and Don'ts belgesi bunların kutulanmış nesne tipleri olduğunu, yerine string, number, boolean ve object yazılması gerektiğini söyler.
• Bildirim dosyasının adını JavaScript dosyasıyla eşleştirmemek; derleyici dosyayı bulamaz veya yanlış biçimde yorumlar.
• TypeScript 6.0'a geçince types listesini eklemeyip yüzlerce "Cannot find name" hatası görmek.
• Geçici declare module "paket"; satırını kalıcı hâle getirmek; o paketteki her şey any kalır.
• Kaynak .ts dosyalarını yayınlayıp outDir kullanmamak; Choosing Compiler Options rehberi bunun kullanıcıların .d.ts yerine .ts dosyalarını yüklemesine yol açabileceğini belirtir.

Sık Sorulan Sorular

.d.ts dosyası JavaScript çıktısına girer mi?

Hayır. Bildirim dosyaları yalnızca tip denetiminde kullanılır ve .js çıktısı üretmez.

@types paketi devDependencies mi dependencies mi olmalı?

Uygulama geliştiriyorsanız devDependencies yeterlidir. Yayınladığınız bir kütüphanenin bildirimleri o tipleri dışa açıyorsa Publishing belgesi dependencies altına koymanızı önerir.

declare ne işe yarar?

declare, değerin başka bir yerde (JavaScript dosyasında, global ortamda, bir pakette) zaten var olduğunu ve burada yalnızca tipinin anlatıldığını söyler. Derleyici bu satırlar için kod üretmez.

Kendi kodum için .d.ts yazmam gerekir mi?

Kodunuz TypeScript ise genellikle hayır; tsc bildirimi declaration ile üretir. Elle yazmak, tipi olmayan JavaScript kodu ve paketler içindir.

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 · modül çözümleme · JavaScript projesini TypeScript'e geçirme · tsconfig.json rehberi · TypeScript ile Node.js · project references