TypeScript ile Node.js Uygulaması Yazmak ve Çalıştırmak

Kurulum

Yeni bir klasörde projeyi başlatıp iki paketi geliştirme bağımlılığı olarak kurun. TypeScript kurulumunun diğer yollarını TypeScript kurulumu yazısında anlattık.

npm init -y
npm install --save-dev typescript @types/node

package.json dosyasına "type": "module" ekleyin. Modül seçim rehberi, ES modülü üretmek istiyorsanız bunu ya da .mts uzantısını kullanmanızı hatırlatıyor. Derleme ve çalıştırma için iki betik de ekleyebilirsiniz:

{
  "name": "ts-node-ornek",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "devDependencies": {
    "@types/node": "^24.19.2",
    "typescript": "^6.0.3"
  }
}

Node.js için tsconfig.json

{
  "compilerOptions": {
    "module": "nodenext",
    "lib": ["esnext"],
    "types": ["node"],
    "rootDir": "./src",
    "outDir": "./dist",
    "verbatimModuleSyntax": true,
    "sourceMap": true
  },
  "include": ["src"]
}

• module: nodenext: Modül referansına göre Node.js 12 ve sonrasında çalışacak uygulama ve kütüphaneler için doğru module değerleri yalnızca node16, node18, node20 ve nodenext değerleridir. nodenext ayrıca moduleResolution: nodenext, esModuleInterop ve target: esnext anlamına gelir.
• lib: ["esnext"]: Tarayıcı (DOM) tanımlarını dışarıda bırakır. Bu ayar 5.9'daki tsc --init şablonunun Node.js önerisidir; lib ayrıntıları için target ve lib yazısına bakın.
• types: ["node"]: TypeScript 6.0'da types varsayılanı boş dizi oldu; @types/node kurulu olsa bile listede yoksa yüklenmez.
• rootDir ve outDir: 6.0'da rootDir varsayılanı tsconfig klasörü olduğu için açıkça ./src yazıyoruz; yoksa çıktı dist/src altına gider.
• verbatimModuleSyntax: Modül seçim rehberinin Node.js için önerdiği ayardır. Yalnızca tip olan importların import type ile yazılmasını şart koşar, diğer importları çıktıya olduğu gibi taşır.

İlk uygulama

// src/ayar.ts
export interface Ayar {
  port: number;
  ortam: string;
}

export function ayarOku(): Ayar {
  const port = Number(process.env.PORT ?? "3000");
  return { port, ortam: process.env.NODE_ENV ?? "development" };
}

// src/index.ts
import { readFile } from "node:fs/promises";
import { ayarOku, type Ayar } from "./ayar.js";

const ayar: Ayar = ayarOku();
const paket = JSON.parse(await readFile("package.json", "utf8"));
console.log(`${paket.name} ${ayar.ortam} ortamında, port ${ayar.port}`);

./ayar.ts dosyasını import ederken ./ayar.js yazdığımıza dikkat edin: TypeScript çıktıdaki dosyanın adını kullanmanızı bekler. type Ayar ise yalnızca tip olduğu için verbatimModuleSyntax bu kısmı çıktıdan siler. Derleyip çalıştıralım:

npx tsc
node dist/index.js
# ts-node-ornek development ortamında, port 3000
PORT=8080 NODE_ENV=production node dist/index.js
# ts-node-ornek production ortamında, port 8080

dist/index.js dosyasında import satırları import { ayarOku } from "./ayar.js"; biçiminde kaldı; tip bilgisi silindi, top-level await ise ES modülü olduğu için olduğu gibi korundu.

Bu kurulumda sık görülen hatalar

İlk denememizde types satırı yoktu ve importta uzantı eksikti. Derleyicinin verdiği hatalar şunlardı:

src/ayar.ts(7,23): error 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.
src/index.ts(1,26): error TS2591: Cannot find name 'node:fs/promises'. 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.
src/index.ts(2,36): error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './ayar.js'?

@types/node paketi kurulu olduğu halde TS2591 aldık, çünkü 6.0'da types listesi boştu. Sürüm notları da 6.0'a geçen birçok projenin "types": ["node"] eklemesi gerekeceğini söylüyor. TS2835 ise ES modülü içinde uzantısız göreli import yazıldığında gelir; Node.js'in ES modül çözümlemesi uzantısız yolları desteklemez.

Son satırdaki hata 6.0 ile geldi: tsconfig dosyası olan bir klasörde npx tsc src/index.ts yazdığımızda derleyici error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Use '--ignoreConfig' to skip this error. mesajını verdi. Önceki sürümler bu durumda tsconfig dosyasını sessizce yok sayıyordu.

ES modülü mü, CommonJS mi?

nodenext yalnızca ES modülü üretmez; her dosyanın biçimini Node.js'in kurallarına göre belirler ve çıktıyı buna göre yazar. Modül referansındaki kurallar şöyle:

Aynı projeden "type": "module" satırını sildiğimizde dosyalar CommonJS sayıldı. verbatimModuleSyntax açıkken her import ve export için TS1295 ve TS1287 hataları geldi; ayarı kapattığımızda bile top-level await için TS1309: The current file is a CommonJS module and cannot use 'await' at the top level. hatası kaldı. Modül biçimleri arasındaki etkileşimi ESM ve CJS yazısında ayrıntılı anlattık. TypeScript 5.8 sürüm notlarına göre nodenext, Node.js 22 ile gelen ve CommonJS dosyadan ES modülünü require() ile yüklemeye izin veren davranışı da modelliyor.

Derlemeden çalıştırma ve erasableSyntaxOnly

TypeScript dokümantasyonuna göre Node.js 23.6 sürümünden itibaren TypeScript dosyalarını doğrudan çalıştırma desteğini bayrak gerektirmeden sunuyor. Bu modda tipler basitçe silinir (type stripping), bu yüzden yalnızca çalışma anında karşılığı olmayan TypeScript sözdizimi desteklenir. Desteklenmeyen yapılar: enum bildirimleri, çalışma anı kodu içeren namespace ve module blokları, sınıflardaki parametre özellikleri, import = ve export = atamaları ile <number>deger biçimindeki eski tip dönüştürmeleri. Node.js tarafındaki ayrıntılar ve sürüm durumu için Node.js belgelerine bakın.

TypeScript 5.8 ile gelen erasableSyntaxOnly seçeneği, bu yapıları derleme sırasında hata olarak gösterir; böylece kodunuzun silme yoluyla çalıştırılamayacağını çalıştırmadan önce öğrenirsiniz:

enum Durum {
// TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
  Aktif,
  Pasif,
}

class Kullanici {
  constructor(public ad: string) {}
// TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
}

const n = <number>(1 as unknown);
// TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
console.log(Durum.Aktif, new Kullanici("Ece").ad, n);

Aynı işi silinebilir sözdizimiyle şöyle yazabilirsiniz. enum yerine as const nesnesi ve alan bildirimi kullandık; bu dosya --erasableSyntaxOnly ile hatasız derlendi ve çıktısı 0 Ece oldu. enum alternatiflerini enum yazısında karşılaştırdık.

const Durum = {
  Aktif: 0,
  Pasif: 1,
} as const;
type Durum = (typeof Durum)[keyof typeof Durum];

class Kullanici {
  ad: string;
  constructor(ad: string) {
    this.ad = ad;
  }
}

const d: Durum = Durum.Aktif;
console.log(d, new Kullanici("Ece").ad); // 0 Ece

Dokümantasyon bu seçeneği verbatimModuleSyntax ile birlikte kullanmayı öneriyor. Kodu doğrudan çalıştırırken göreli importlarda .ts uzantısı yazmanız gerekir; TypeScript buna normalde TS5097 hatasıyla itiraz eder (An import path can only end with a '.ts' extension when 'allowImportingTsExtensions' is enabled.). Aynı kodu ayrıca tsc ile derlemek istiyorsanız 5.7 ile gelen rewriteRelativeImportExtensions seçeneğini açın: göreli ./ayar.ts yolu çıktıda ./ayar.js olarak yazılır. Denememizde bu seçenekle derleme hatasız tamamlandı ve dist/index.js beklenen çıktıyı verdi.

Yayına alma

Sunucuda en sade yöntem, npm run build ile dist klasörünü üretip uygulamayı node dist/index.js ile başlatmaktır. sourceMap açık olduğu için hata yığınlarını kaynak dosyalara eşlemek kolaylaşır. REST API örneği için Node.js REST API geliştirme yazısına, süreç yönetimi için PM2 ile cluster yazısına bakabilirsiniz.

Sık Sorulan Sorular

TypeScript'te Node.js için module değeri ne olmalı?

Kodu tsc ile derleyip Node.js ile çalıştırıyorsanız nodenext. Sabit bir davranış istiyorsanız node20 gibi sürüme bağlı bir değer seçebilirsiniz. Paketleyici kullanıyorsanız modül seçim rehberi moduleResolution: bundler öneriyor.

@types/node kurdum ama process bulunamıyor, neden?

TypeScript 6.0'da types varsayılanı boş dizi. tsconfig dosyasına "types": ["node"] eklemeniz gerekir.

Importlarda neden .ts yerine .js yazıyorum?

TypeScript import yollarını değiştirmez ve Node.js derlenmiş .js dosyasını yükler. Bu yüzden çalışma anında var olacak dosyanın adını yazarsınız. .ts yazmak istiyorsanız rewriteRelativeImportExtensions seçeneğini kullanın.

erasableSyntaxOnly açmalı mıyım?

Kodu tipleri silen bir araçla, örneğin Node.js'in yerleşik desteğiyle, doğrudan çalıştıracaksanız evet; desteklenmeyen sözdizimini derleme anında yakalar. Yalnızca tsc çıktısını çalıştırıyorsanız zorunlu değildir.

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 · Node.js nedir · Node.js REST API · ESM ve CJS modül çözümleme · target ve lib · paths ve rootDir