TypeScript Modülleri: Import, Export ve import type

Bir TypeScript modülü, en üst seviyede en az bir import ya da export içeren bir dosyadır. İçinde tanımlanan her şey siz export etmedikçe dosyaya özeldir ve diğer dosyalar ihtiyaç duyduklarını import eder. Söz dizimi, JavaScript'in ES modülü söz dizimi artı birkaç yalnızca tipe özel biçimdir.

// math.ts: this file is a module because it has exports.
export interface Point {
  x: number;
  y: number;
}

export const ORIGIN: Point = { x: 0, y: 0 };

export function distance(a: Point, b: Point): number {
  return Math.hypot(b.x - a.x, b.y - a.y);
}

// One default export per file, at most.
export default function describe(p: Point): string {
  return `(${p.x}, ${p.y})`;
}

const secret = 42; // not exported: invisible to other files

console.log(describe({ x: 3, y: 4 }), distance(ORIGIN, { x: 3, y: 4 })); // (3, 4) 5

Named ve Default Export'lar

Bir projede birçok dosya vardır, bu yüzden import eden taraf şöyle görünür. Default export süslü parantez olmadan import edilir ve herhangi bir ad alabilir; named export'lar süslü parantez içine yazılır ve siz as ile yeniden adlandırmadıkça adlarını korur.

// main.ts
import describe, { distance, ORIGIN, type Point } from "./math.js";
import { distance as dist } from "./math.js"; // renamed on import
import * as math from "./math.js";            // everything, as one object

const p: Point = { x: 6, y: 8 };
console.log(describe(p), distance(ORIGIN, p), dist(p, p), math.ORIGIN);

Yeniden export'lar, tek bir dosyanın (çoğu zaman index.ts) bir klasörün public API'sini toplamasını sağlar. Canlı bağlamalar ve modül önbelleği gibi düz JavaScript modül davranışları ES modülleri sayfasında anlatılır.

import type ve export type

Tipler çalışma zamanında yoktur, bu yüzden yalnızca tip olarak kullanılan bir import'un yükleyeceği bir şey yoktur. import type bunu açıkça söyler ve ifade JavaScript çıktısından kaybolur. type belirteci, normal bir import içindeki tek bir ad üzerinde de çalışır.

import type { User } from "./models.js";        // whole statement erased
import { saveUser, type Settings } from "./api.js"; // only saveUser survives

export type { User };                            // re-export a type only
export type UserId = User["id"];

Anahtar kelime olmadan da TypeScript yalnızca tip olduğunu görebildiği adları çıkarır. İki ayar anahtar kelimeyi zorunlu kılar:

• verbatimModuleSyntax: true, type ile işaretlenmemiş her import'u korur; bu yüzden işaretlenmemiş bir tip import'u TS1484 hatasıdır: 'Point' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.
• .ts dosyalarını doğrudan Node'da çalıştırmak (type stripping) tip işaretlemelerini siler ama diğer dosyalara bakmaz. İşaretlenmemiş bir import { Point } kodda kalır ve Node çalışma zamanında SyntaxError: The requested module './math.ts' does not provide an export named 'Point' ile başarısız olur.

Her yalnızca tip import'una type yazmak iki durumda da çalışır, bu yüzden edinilmesi gereken alışkanlık budur.

Cannot Find Module

Bir import'taki yol bir dosyaya ya da tipleri olan bir pakete çıkmıyorsa derleyici TS2307 hatasıyla durur. Görmek için bunu çalıştırın:

// This does not compile: there is no utils file next to this one.
import { formatPrice } from "./utils.js";

console.log(formatPrice(9.5));

Çıktı şudur: index.ts(2,29): error TS2307: Cannot find module './utils.js' or its corresponding type declarations. Olağan nedenler:

• Göreli bir yolda yazım hatası ya da eksik bir ./ (onsuz ad node_modules içinde aranır).
• Tiplerini içermeyen bir JavaScript paketi: varsa @types/{package} paketini kurun ya da onun için bir declaration dosyası yazın.
• Paketin package.json dosyasındaki exports alanında listelenmeyen bir alt yol. node16, nodenext ve bundler çözümlemesi altında yalnızca listelenen giriş noktaları import edilebilir.

ES Modülü mü CommonJS Çıktısı mı

Her zaman import ve export yazarsınız. tsconfig.json içindeki module seçeneği hangi JavaScript'in çıkacağına karar verir.

// Source, the same in both cases
import { add } from "./math.js";
console.log(add(1, 2));

// module: nodenext, in a package with "type": "module"
import { add } from "./math.js";
console.log(add(1, 2));

// module: nodenext, in a package without "type": "module"
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const math_js_1 = require("./math.js");
console.log((0, math_js_1.add)(1, 2));

node16, node18, node20 ya da nodenext ile TypeScript her dosya için Node'un kendi kurallarını izler:

module: "esnext" ya da "preserve" ile çıktı import/export ifadelerini korur; Vite ve esbuild gibi bundler'ların beklediği de budur. İki modül sisteminin çalışma zamanındaki farkları CommonJS ve ESM sayfasındadır.

Import'larda Dosya Uzantıları

module: node16 ya da nodenext altında bir ES modülü dosyası, Node'un gerçekten yükleyeceği dosyayı adlandırmak zorundadır ve bu, derlenmiş .js dosyasıdır. TypeScript tip kontrolü için ./math.js yolunu math.ts dosyasına eşler.

import { add } from "./math";    // error TS2835 in an ES module file
import { add } from "./math.js"; // correct: the path as it exists after compiling

Hata metni şudur: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './math.js'? Aynı ayarlar altındaki CommonJS dosyaları uzantıyı yazmayabilir, çünkü require uzantıları kendisi dener.

İki başka kurulum kuralı değiştirir:

• moduleResolution: "bundler" (module değeri esnext, preserve ya da commonjs iken), bundler çözdüğü için uzantısız ./math yolunu kabul eder.
• rewriteRelativeImportExtensions: true, Node .ts dosyasını doğrudan çalıştırdığında da işleyen ./math.ts yolunu yazmanıza izin verir ve çıktıda onu ./math.js olarak yeniden yazar.

Modül Çözümleme ve paths

"zod" gibi çıplak bir ad için TypeScript node_modules içine bakar, paketin package.json dosyasını (exports ve types alanlarını) okur ve son çare olarak node_modules/@types/zod konumuna düşer. Göreli adlar (./, ../) import eden dosyadan itibaren çözülür. Bir .json dosyası da import edilebilir; bunun için gereken ayarlar JSON sayfasındadır.

tsconfig.json içindeki paths, kendi klasörleriniz için takma adlar ekler:

{
    "compilerOptions": {
        "module": "esnext",
        "moduleResolution": "bundler",
        "paths": {
            "@lib/*": ["./src/lib/*"]
        }
    }
}

paths yalnızca tip kontrolünü etkiler. Üretilen dosya hâlâ import { v } from "@lib/util" der, bu yüzden çalışma zamanında onu başka bir şeyin çözmesi gerekir: aynı takma adla yapılandırılmış bir bundler ya da package.json içindeki Node imports alanı ("#lib/*": "./dist/lib/*" gibi # ile başlayan takma adlar), ki bu hiçbir ek araç olmadan çalışır. baseUrl TypeScript 7'de kaldırıldı (TS5102 hatası); paths girdilerini tsconfig.json dosyasına göre, başında ./ olacak şekilde yazın.