10.1 import と export

基本形

// lib.ts
export const greet = (name: string) => `Hello, ${name}`;
export type User = { name: string };

// main.ts
import { greet, type User } from "./lib.ts";

import type — 型だけを取り込む

型は実行時に消えるため、型だけを import している場合、その行ごと消えます。明示すると意図が伝わり、消えることも保証されます。

import type { User } from "./types.ts";        // 型だけ。実行時には消える
import { greet, type User } from "./lib.ts";   // 値と型を混ぜる書き方

default export は避ける

// 名前付き export（推奨）
export const greet = () => {};
import { greet } from "./lib.ts";

// default export
export default function () {}
import whateverName from "./lib.ts";     // 名前を自由に付けられてしまう

10.2 ESM と CJS

2つのモジュール方式がある

どちらで動くかは package.json が決める

{
	"type": "module"      // ← ESM。省略すると CJS
}

実際の違い

// main-dirname.ts
console.log(typeof __dirname === "undefined" ? "__dirname は使えない" : "__dirname は使える");
console.log(typeof require === "undefined" ? "require は使えない" : "require は使える");

$ node main-dirname.ts               # package.json に type がない場合
__dirname は使える
require は使える

$ node main-dirname.ts               # "type": "module" の場合
__dirname は使えない
require は使えない

const dir = import.meta.dirname;      // ESM でのファイルの場所

よく出るエラーと原因

拡張子の扱い

ESM ESM では拡張子の省略ができません。しかも書くのは出力後の拡張子です。

import { greet } from "./lib";        // ESM では動かない
import { greet } from "./lib.js";     // ← .ts を書いても .js と書く（出力後の名前）
import { greet } from "./lib.ts";     // Node で直接 .ts を実行する場合はこちら

default export の食い違い

// CJS のライブラリ
module.exports = function foo() {};

// ESM から使う
import foo from "some-cjs-lib";       // 動く場合と動かない場合がある
import * as foo from "some-cjs-lib";  // foo.default になることがある

ESMCJS module.exports と export default は別の仕組みです。Node とバンドラで解釈が異なることもあります。

{
	"compilerOptions": {
		"esModuleInterop": true        // 相互運用を助ける（既定で有効なことが多い）
	}
}

「型は通るのに実行時に x is not a function になる」ときは、まずこの食い違いを疑ってください。

10.3 .d.ts と @types

.d.ts は型だけを書くファイル

// lib.d.ts — 実装はなく、形だけを宣言する
export declare function greet(name: string): string;
export declare const VERSION: string;

tsc は .ts をコンパイルするとき、declaration: true を指定すると .d.ts も出力します。ライブラリを配布するときは、.js と .d.ts をセットで配ります。

型定義がどこから来るか

TypeScript 7 では types への明示が必要

TS7 02. 実行環境で触れたとおり、@types/* を入れるだけでは読み込まれません。

{
	"compilerOptions": {
		"types": ["node"]        // ← 使うものを列挙する
	}
}

10.4 型定義がないライブラリ

まず @types を探す

$ npm i -D @types/ライブラリ名

見つからなければ、次の3つから選びます。

① 最小限の .d.ts を自分で書く

// types/legacy-lib.d.ts
declare module "legacy-lib" {
	export function doSomething(input: string): number;
}

{
	"compilerOptions": {
		"typeRoots": ["./node_modules/@types", "./types"]
	},
	"include": ["src/**/*.ts", "types/**/*.d.ts"]
}

使う関数だけ書けば十分です。全体を網羅する必要はありません。

② any として受け入れる（暫定）

// types/legacy-lib.d.ts
declare module "legacy-lib";      // すべて any になる

import { doSomething } from "legacy-lib";

// any のまま使わず、受け口で unknown にする
const result: unknown = doSomething("x");
if (typeof result === "number") {
	console.log(result.toFixed(2));
}

③ ラッパーを1枚かぶせる

実務で最も勧められる形です。型のない世界を1ファイルに閉じ込めます。

// src/legacy-wrapper.ts — ここだけが型のない世界に触れる
import * as legacy from "legacy-lib";

export function doSomething(input: string): number {
	const r: unknown = (legacy as { doSomething(s: string): unknown }).doSomething(input);
	if (typeof r !== "number") {
		throw new Error(`legacy-lib が想定外の値を返しました: ${String(r)}`);
	}
	return r;
}

他のファイルは legacy-wrapper.ts だけを使います。ライブラリを差し替えるときも、直すのはこのファイルだけです。