TypeScriptのモジュール: import・export と import type

TypeScriptのモジュールとは、トップレベルに import か export が少なくともひとつあるファイルです。その中で宣言したものは export しない限りファイルの中だけで使え、ほかのファイルは必要なものを import します。構文はJavaScriptの ES モジュールの構文に、型専用の書き方がいくつか加わったものです。

// 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

名前付きエクスポートとデフォルトエクスポート

プロジェクトには多くのファイルがあるので、import する側は次のようになります。デフォルトエクスポートは波かっこなしで import し、好きな名前を付けられます。名前付きエクスポートは波かっこの中に書き、as で名前を変えない限りそのままの名前で使います。

// 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);

再エクスポートを使うと、ひとつのファイル（多くは index.ts）にフォルダーの公開 API をまとめられます。ライブバインディングやモジュールのキャッシュといったJavaScriptのモジュール自体の動作は、ES モジュールで説明しています。

import type と export type

型は実行時には存在しないので、型としてしか使わない import には読み込むものがありません。import type はそれを明示し、その文はJavaScriptの出力から消えます。type 修飾子は、普通の import の中の個々の名前にも付けられます。

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"];

キーワードがなくても、TypeScriptは型だけだとわかる名前を取り除きます。次の2つの設定では、このキーワードが必須になります:

• verbatimModuleSyntax: true は type の付いていない import をすべて残すので、印のない型の import はエラー TS1484 'Point' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled. になります。
• Node で .ts ファイルを直接実行する（型除去）と、型注釈は取り除かれますが、ほかのファイルは見ません。印のない import { Point } はコードに残り、Node は実行時に SyntaxError: The requested module './math.ts' does not provide an export named 'Point' で失敗します。

型だけの import にはいつも type を書くようにすれば、どちらの場合でも動くので、習慣にしておきましょう。

Cannot Find Module

import のパスがファイルや型付きのパッケージにたどり着かないと、コンパイラーはエラー TS2307 で止まります。次のブロックを実行して確認してください:

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

console.log(formatPrice(9.5));

出力は index.ts(2,29): error TS2307: Cannot find module './utils.js' or its corresponding type declarations. です。よくある原因:

• 相対パスのタイプミスや、./ の書き忘れ（なければ名前は node_modules から探されます）。
• 型を同梱していないJavaScriptのパッケージ: @types/{package} があればインストールし、なければ宣言ファイルを書きます。
• パッケージの package.json の exports フィールドに載っていないサブパス。node16、nodenext、bundler の解決方式では、載っているエントリーポイントしか import できません。

ES モジュールと CommonJS の出力

書くのは常に import と export です。どんなJavaScriptが出力されるかは、tsconfig.json の module オプションで決まります。

// 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、nodenext では、TypeScriptはファイルごとに Node 自身のルールに従います:

module: "esnext" や "preserve" では、出力に import/export がそのまま残ります。Vite や esbuild のようなバンドラーが期待するのはこの形です。2つのモジュールシステムの実行時の違いは CommonJS と ESM で説明しています。

import の拡張子

module: node16 や nodenext では、ES モジュールのファイルは Node が実際に読み込むファイルを指定しなければならず、それはコンパイル後の .js ファイルです。型チェックのときには、TypeScriptは ./math.js を math.ts に対応させます。

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

エラーの文面は Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './math.js'? です。同じ設定でも CommonJS のファイルでは拡張子を省略できます。require が自分で拡張子を試すからです。

ルールが変わる設定がほかに2つあります:

• moduleResolution: "bundler"（module が esnext、preserve、commonjs のいずれか）では、バンドラーが解決するので拡張子なしの ./math を受け付けます。
• rewriteRelativeImportExtensions: true を使うと、Node が .ts ファイルを直接実行するときにも通るパス ./math.ts と書けて、出力では ./math.js に書き換えられます。

モジュール解決と paths

"zod" のような裸の名前の場合、TypeScriptは node_modules を探し、パッケージの package.json（exports と types のフィールド）を読み、見つからなければ node_modules/@types/zod を使います。相対の名前（./、../）は import するファイルの位置から解決されます。.json ファイルも import できます。そのための設定は JSON のページにあります。

tsconfig.json の paths で、自分のフォルダーにエイリアスを追加できます:

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

paths が影響するのは型チェックだけです。出力されるファイルには import { v } from "@lib/util" のまま残るので、実行時にはほかの何かが解決しなければなりません。同じエイリアスを設定したバンドラーか、package.json の Node の imports フィールド（"#lib/*": "./dist/lib/*" のように # で始まるエイリアス）です。後者は追加のツールなしで動きます。baseUrl は TypeScript 7 で廃止されました（エラー TS5102）。paths のエントリーは、tsconfig.json からの相対パスとして ./ から書きましょう。