tsconfig ve strict mod

tsconfig.json Nedir

Bir klasörde tsconfig.json bulunması, o klasörün bir TypeScript projesinin kökü olduğunu gösterir. Dosya hangi dosyaların kontrol edileceğini ve hangi kuralların uygulanacağını tanımlar. tsc'yi dosya adı vermeden çalıştırdığınızda derleyici bu dosyayı bulunduğunuz klasörden başlayıp yukarı doğru arar.¹

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "strict": true,
    "noEmit": true
  },
  "include": ["src"]
}

strict Modu

TypeScript'in sıkılığı tek bir anahtardan çok bir ayar düğmesi gibidir: kontrolleri tek tek açıp kapatabilirsiniz. "strict": true hepsini birden açar.³

Bayrak listesi TSConfig referansındaki strict ailesidir.⁴ En çok fark edeceğiniz ikisi noImplicitAny ve strictNullChecks'tir:

function getProduct(id) {}
// Hata: Parameter 'id' implicitly has an 'any' type.

try {
  await fetchProducts();
} catch (error) {
  console.log(error.message);
  // Hata: 'error' is of type 'unknown'.
}

TypeScript 6.0 ile strict varsayılan olarak açık hale geldi, TypeScript 7 de bu varsayılanı korudu.⁵⁶ Yine de dosyaya "strict": true yazmak niyetinizi açıkça gösterir. Eski bir projeyi taşırken bile strict'i tamamen kapatmak yerine bayrakları tek tek açın.

strict'e Ek Bayraklar

noUncheckedIndexedAccess

strict'in parçası değildir ama en faydalı ek bayraktır. Dizi elemanına ya da index signature'lı bir nesneye erişimin sonucuna undefined ekler.⁷ Dizinin boş olabileceğini unutmanızı engeller:

const products: Product[] = await fetchProducts();

const first = products[0]; // Product | undefined
console.log(first.name);
// Hata: 'first' is possibly 'undefined'.

if (first) {
  console.log(first.name); // artık Product
}

Matt Pocock bu bayrağın aslında strict'e dahil olması gerektiğini söyler.⁸ TypeScript 7'de tsc --init de onu açık olarak üretir. Vite şablonunda ise kapalıdır; kendiniz eklemeniz gerekir.

Diğerleri

Matt Pocock ise noUnusedLocals gibi bayrakları "gürültülü" bulur ve yalnızca isteyenlerin eklemesini önerir.⁸ İkisi de geçerli bir seçim; ekip olarak birini seçin.

React Uygulaması İçin Ayarlar

Vite ya da Next.js kullanan bir uygulamada JavaScript'i TypeScript üretmez, bundler üretir. TypeScript yalnızca tip denetleyicisi olarak çalışır. Bu yüzden ayarlar buna göre seçilir:

verbatimModuleSyntax açıkken yalnızca tip olan import'ları şöyle yazarsınız:

import type { Product } from "./types";
import { formatPrice, type CartItem } from "./cart";

Vite Şablonundaki Üç Dosya

npm create vite@latest -- --template react-ts (create-vite 9.2) üç dosya üretir:

Uygulama kodu ile Node'da çalışan yapılandırma farklı ortamlarda çalıştığı için ayrı ayarlarla kontrol edilir. tsconfig.app.json'ın özü şöyledir:

{
  "compilerOptions": {
    "target": "es2023",
    "lib": ["ES2023", "DOM"],
    "module": "esnext",
    "types": ["vite/client"],
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "verbatimModuleSyntax": true,
    "moduleDetection": "force",
    "noEmit": true,
    "jsx": "react-jsx",
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "erasableSyntaxOnly": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"]
}

Dosyada strict yok, çünkü şablonun kurduğu TypeScript 6.0'da zaten varsayılan. types: ["vite/client"] ise import.meta.env ve resim, CSS import'ları için tipleri ekler.¹⁴

references kullanan bir projede tip kontrolü tsc -b (--build) ile yapılır; bu komut referans verilen projeleri bulur ve doğru sırayla kontrol eder.¹⁵ Şablondaki build script'i de tsc -b && vite build'dir.

Next.js'te tsconfig

Next.js projesi create-next-app ile açıldığında tsconfig.json hazır gelir; var olan bir projede bir dosyayı .ts yapıp next dev çalıştırdığınızda Next.js dosyayı kendisi oluşturur.¹⁶ Üretilen dosyada strict, noEmit, moduleResolution: "bundler", jsx: "react-jsx", isolatedModules, @/* path alias'ı ve Next.js'in editör eklentisi ("plugins": [{ "name": "next" }]) bulunur. Ayrıca next-env.d.ts adında, elle düzenlenmemesi gereken bir tip dosyası üretilir.¹⁶

next build tip hatası varsa build'i durdurur. typescript.ignoreBuildErrors bu kontrolü kapatır; dokümantasyon bunu ancak tip kontrolünü başka bir yerde çalıştırıyorsanız önerir.¹⁶

Path Alias

../../../components/ProductCard gibi uzun göreli yollar yerine @/components/ProductCard yazmak için paths kullanılır:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

paths yalnızca TypeScript'e bu eşlemeyi anlatır; çıktıdaki import'ları değiştirmez. Eşlemeyi çalışma anında bundler'ın da bilmesi gerekir.⁴ Vite'ta bunun için vite.config.ts içinde resolve: { tsconfigPaths: true } ayarını açarsınız.¹⁴ Next.js paths'i kendisi okur.

@types Paketleri ve .d.ts

JavaScript ile yazılmış bir kütüphanenin tipleri declaration (.d.ts) dosyalarında durur. Birçok paket bu dosyaları kendisi getirir; getirmeyenler için topluluğun yazdığı tipler @types/ önekiyle yayımlanır (@types/react, @types/node).¹⁷ Bir paketi import ettiğinizde "Could not find a declaration file" hatası alıyorsanız önce npm install -D @types/<paket-adı> deneyin.

TypeScript 6.0'dan itibaren types ayarının varsayılanı boş dizidir: global tipler (örneğin Node'un process'i) artık kendiliğinden yüklenmez, "types": ["node"] gibi açıkça yazmanız gerekir.⁵ Vite şablonundaki types satırları bu yüzden var.

typescript-eslint

tsc tip hatalarını bulur; hatalı ama tip açısından geçerli kalıpları (örneğin beklenmeyen bir Promise) ise linter bulur. ESLint için TypeScript desteğini typescript-eslint sağlar. Tip bilgisini kullanan kurallar için recommendedTypeChecked ya da daha katı strictTypeChecked yapılandırması seçilir ve projectService açılır:¹⁸

// eslint.config.mjs
import js from "@eslint/js";
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";

export default defineConfig({
  files: ["**/*.{ts,tsx}"],
  extends: [
    js.configs.recommended,
    tseslint.configs.recommendedTypeChecked,
  ],
  languageOptions: {
    parserOptions: {
      projectService: true,
    },
  },
});

typescript-eslint, strictTypeChecked'i yalnızca ekibin önemli bir kısmı TypeScript'te deneyimliyse önerir.¹⁹

CI'da Tip Kontrolü

Bundler tip kontrolü yapmadığı için, hatalı kodun ana dala girmemesini garanti etmenin yolu CI'da tsc çalıştırmaktır.²¹ Önce package.json'a bir script ekleyin:

{
  "scripts": {
    "typecheck": "tsc -b"
  }
}

Next.js ya da tek tsconfig'li bir projede değer tsc --noEmit olur. Ardından GitHub Actions iş akışı:²²

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run typecheck

Pull request'te tip hatası varsa bu adım kırmızıya döner. Lint ve test adımlarını aynı job'a ekleyebilirsiniz.

Kendin Dene

• Vite şablonunun tsconfig.app.json dosyasına "noUncheckedIndexedAccess": true ekleyin ve npx tsc -b ile kaç yeni hata çıktığına bakın.

• TS Playground'un TS Config menüsünden strict'i kapatıp açın; aynı kodda hangi hataların kaybolduğunu izleyin.

• @/* alias'ını hem paths hem resolve.tsconfigPaths ile kurun; yalnızca birini açınca editörün ve vite build'in nasıl davrandığını karşılaştırın.

• Bir dosyaya bilerek tip hatası koyup CI iş akışının kırmızıya döndüğünü görün.

Detaylı Öğrenmek İçin

• Yazı: Matt Pocock'un TSConfig Cheat Sheet'i; bundler kullanan ve kullanmayan projeler için hazır bloklar.⁸

• Kitap: Matt Pocock'un Total TypeScript Essentials kitabının "Configuring TypeScript" bölümü; extends, lib, jsx ve project references.²³

• Resmi doküman: TSConfig Reference; her ayarın açıklaması ve örneği.⁴

• Resmi doküman: typescript-eslint'in "Linting with Type Information" rehberi.¹⁸

• Yazı: TypeScript 6.0 duyurusu; değişen varsayılanlar ve baseUrl olmadan paths yazımı.⁵