Модули: import type, verbatimModuleSyntax, moduleResolution

Здесь будет встроен видео-разбор темы (5–7 минут, YouTube / RuTube / VK Видео) — тем, кто лучше воспринимает на слух, текст ниже не обязателен.

В части I импорт означал ровно одно: привезти из соседнего файла значение. В TypeScript у имени появилось второе место жительства. Объявления делятся на те, что заводят значение (const, function, class), и те, что заводят только тип (interface, type). Эти два пространства не пересекаются — поэтому одно имя спокойно живёт в обоих сразу.

ts

// одно имя занято дважды: слева от двоеточия читается тип, справа — значение
type Plugin = { name: string; run(): void };
const Plugin = { name: "поиск", run: () => console.log("ищу") };

const p: Plugin = Plugin;
p.run();
console.log(typeof Plugin);

страница примера

Сначала предположите, что выведет код

Компилятор не жалуется: в позиции типа он ищет имя среди типов, в позиции значения — среди значений, и находит в каждой своё. А теперь представьте эти два объявления в соседнем файле. Строка import { Plugin } from "./plugin.js" сама по себе не отвечает, что именно приехало: тип, значение или оба.

Разница между ними видна не в редакторе, а на запуске. До выполнения доезжают только имена, у которых есть значение.

ts

interface Config {
  level: string;
}
type Handler = (c: Config) => void;
class Runner {
  started = false;
}
const DEFAULTS: Config = { level: "low" };
const onDone: Handler = (c) => console.log(c.level);

console.log(typeof Runner, typeof DEFAULTS, typeof onDone);
console.log(typeof Config);
console.log(typeof Handler);

страница примера

Сначала предположите, что выведет код

На две последние строки компилятор отвечает одинаково: "Config" относится только к типу, но используется здесь как значение. — код TS2693. Но код всё равно выполнился и напечатал undefined дважды: typeof — единственный оператор, которому позволено спрашивать про несуществующие имена, об этом была речь в главе про всплытие. Компилятор предупредил, JavaScript пожал плечами.

Обратная ловушка: enum выглядит как объявление типа, а заводит настоящий объект. Вычеркнуть его нельзя — про это была отдельная статья.

Двусмысленность компилятор решает самостоятельно: он строит программу целиком, открывает ./user.ts, видит, что User — интерфейс, а VERSION — константа, и при сборке выкидывает из списка импорта первое имя. Приём называется стиранием импортов, import elision.

ts

// user.ts:  export interface User { name: string }
//           export const VERSION = "1.0";
// main.ts:  import { User, VERSION } from "./user.js";
//
// в собранном main.js от этой строки остаётся:
//           import { VERSION } from "./user.js";

// то же самое одним файлом — чтобы было что запустить
type User = { name: string };
const VERSION = "1.0";
const u: User = { name: "Рико" };
console.log(u.name, VERSION);

страница примера

Сначала предположите, что выведет код

Пока в списке остаётся хотя бы одно значение, строка импорта живёт. Но если типами оказались все имена, компилятор убирает строку целиком — а вместе с ней и загрузку файла.

Модуль в JavaScript — это не только набор экспортов, но и код, который выполняется при первой загрузке. Регистрация в реестре, установка темы, подключение полифила. Если из соседнего файла вы взяли только тип, всей этой работы не произойдёт.

ts

// registry.ts: console.log("registry выполнен");
//              export interface Plugin { name: string }
// main.ts:     import { Plugin } from "./registry.js";
//              const p: Plugin = { name: "search" };
//              console.log("main:", p.name);
//
// собранный main.js:  const p = { name: "search" };
//                     console.log("main:", p.name);
//                     export {};

const p = { name: "search" };
console.log("main:", p.name);

страница примера

Сначала предположите, что выведет код

Ошибку такого рода не видно ни в редакторе, ни в диагностике: типы сходятся, сборка зелёная, просто одна из веток программы молча не выполнилась. Дальше в статье будет две записи, которые загрузку сохраняют.

С другой стороны стирание выглядит как имя-призрак: компилятор про него знает, а в собранном файле его нет. Ровно то же обещание даёт declare — «такое имя есть, поверь на слово», — и последствие видно сразу.

ts

// declare обещает компилятору имя, которого он не видел.
// import type даёт компилятору то же обещание.
declare const registry: { add(name: string): void };

console.log("до вызова");
registry.add("search");
console.log("после вызова");

страница примера

Сначала предположите, что выведет код

Диагностики нет ни одной — компилятор поверил на слово. А теперь главное: чтобы стереть имя, нужно знать, что лежит в соседнем файле. Половина инструментов в вашей сборке этого не знает. esbuild, swc, Babel и сам Node в режиме node app.ts обрабатывают файл в одиночку и не открывают соседей. Для них import { User } — просто импорт: удалить страшно (вдруг это значение), оставить страшно (вдруг в собранном соседе такого экспорта нет). Флаг isolatedModules как раз и проверяет, что ваш код переживёт однофайловую сборку.

Ответ языка — не заставлять догадываться, а пометить намерение прямо в коде. Пометок две: слово type перед всем списком и модификатор type перед отдельным именем.

ts

// import type { User } from "./user.js";          весь импорт — про типы
// import { type User, VERSION } from "./user.js"; помечено одно имя из двух
// export type { User };                           на экспорте так же

type User = { name: string };
const VERSION = "1.0";
const u: User = { name: "Рико" };
console.log(u.name, VERSION);

страница примера

Сначала предположите, что выведет код

Формы выглядят взаимозаменяемыми, но в собранном файле от них остаётся разное — и разница появляется только вместе с флагом из следующего раздела.

Строка в исходнике	Что остаётся в сборке
`import { User } from "./user.js"`, где `User` — тип	ничего: строка исчезает молча, вместе с загрузкой файла
`import type { User } from "./user.js"`	ничего, но это написано вами, а не выведено компилятором
`import { type User } from "./user.js"`	`import {} from "./user.js"` — файл всё-таки загрузится (только при `verbatimModuleSyntax`)
`import { type User, VERSION } from "./user.js"`	`import { VERSION } from "./user.js"`
`import "./user.js"`	остаётся всегда: стирать в этой строке нечего

Обратная сторона пометки: помеченное имя перестаёт быть значением. Попытка позвать new Session() после import type { Session } даёт TS1361: "Session" невозможно использовать как значение, так как он был импортирован с помощью "import type". У экспорта есть двойник TS1362 для export type, а при повторном экспорте типа компилятор просит явную форму: Для повторного экспорта типа при включенном "verbatimModuleSyntax", необходимо использовать "export type". — TS1205.

Практическое правило короткое: спросите себя, встречается ли имя где-нибудь, кроме позиции типа. new, вызов, instanceof, extends в объявлении класса, обращение к статическому полю — это позиции значения, и import type там всё сломает.

ts

class HttpError extends Error {
  status = 500;
}

function describe(e: unknown): string {
  // instanceof спрашивает про значение: имя должно доехать до выполнения,
  // поэтому импортировать такой класс через import type нельзя
  return e instanceof HttpError ? "статус " + e.status : "обычная ошибка";
}

console.log(describe(new HttpError()));
console.log(describe(new Error("сеть")));

страница примера

Сначала предположите, что выведет код

Пометка type не ослабляет проверку: тип работает ровно так же, как без неё. Меняется только собранный файл.

Флаг переводит компилятор из режима «догадайся» в режим «делай, как написано». Из строки импорта убирается ровно то, что помечено словом type, — и больше ничего. Ни одно имя не исчезает по догадке, ни одна строка не пропадает молча.

Взамен появляется требование к вам: если имя — тип, пометьте его сами.

ts

// tsconfig.json: "verbatimModuleSyntax": true
//
// import { User } from "./user.js";
//   TS1484: "User" является типом и должен быть импортирован
//   с использованием импорта только типа
//
// import type { User } from "./user.js";  строка исчезнет целиком
// import { type User } from "./user.js";  останется import {} from "./user.js"

type User = { name: string };
const u: User = { name: "Рико" };
console.log(u.name);

страница примера

Сначала предположите, что выведет код

Строка в исходнике	Без флага	С флагом
`import { User }`, где `User` — тип	строка исчезает молча	TS1484
`import type { User }`	строка исчезает	строка исчезает
`import { type User }`	строка исчезает	`import {} from …`
`export { User }`, где `User` — тип	`export {}`	TS1205

Третья строка таблицы и есть лекарство из врезки про пропавший побочный эффект: import { type User } from "./theme.js" оставляет в сборке пустой импорт, файл загружается, тема применяется. Без флага та же запись стирается целиком — компилятор всё ещё считает, что знает лучше.

Что флаг даёт в сумме. tsc и однофайловые компиляторы перестают расходиться: esbuild видит в файле ровно ту же информацию, что и tsc, и выдаёт тот же результат. Побочные эффекты модулей больше не пропадают. И читатель кода видит намерение автора, не открывая соседний файл, — в ревью это ценнее, чем кажется. Заготовка из tsc --init, с которой начиналась глава, включает флаг сама; отдельно решать «а нужно ли» в новом проекте не приходится.

«Слово в слово» работает в обе стороны. Если файл по правилам Node оказался модулем CommonJS — расширение .cts или отсутствие "type": "module" в package.json, — то писать в нём синтаксис ECMAScript под этим флагом уже нельзя: компилятор не станет молча переводить import в require.

ts

// legacy.cts при "verbatimModuleSyntax": true
//
// import { VERSION } from "./user.js";
//   TS1286: Импорты и экспорты ECMAScript невозможно записать
//   в файл CommonJS в разделе "verbatimModuleSyntax"
//
// в таком файле пишут формы, которые Node понимает буквально:
// import user = require("./user.js");
// export = { VERSION: "1.0" };

const user = { VERSION: "1.0" };
console.log(user.VERSION);

страница примера

Сначала предположите, что выведет код

Это те самые import ... = require(...) и export = из статьи про нестираемый синтаксис. В новом коде они не нужны — но если проект наполовину CommonJS, флаг заставит признать это честно, а не оставит на усмотрение компилятора.

Настройка module отвечает за то, что компилятор напишет в собранном файле. Настройка moduleResolution — за то, как он ищет файл по строке в кавычках. Вопросы разные, а путают их постоянно, потому что оба про модули.

ts

type User = import("./user.js").User;

const u: User = { name: "Рико" };
console.log(u.name);

страница примера

Сначала предположите, что выведет код

Диагностика — TS2307: Не удается найти модуль "./user.js" или связанные с ним объявления типов. Обратите внимание, что компилятор жалуется на поиск, а на выполнение это никак не влияет: аннотация стёрлась, объект остался. И заодно понятно, зачем компилятору вообще открывать соседний файл — за содержимым типа.

Долгие годы по умолчанию работал алгоритм Node образца 2015 года: node, он же node10. Искать ./user.ts, потом ./user/index.ts, потом подниматься по node_modules и читать поле main. Про поле exports в package.json он не знает ничего — а современные пакеты раздают типы именно через него.

ts

// пакет отдаёт типы через "exports":
//   { "exports": { ".": { "types": "./lib/i.d.ts", "default": "./lib/i.js" } } }
//
// при "moduleResolution": "node10" на import { A } from "pkg" получаем:
//   TS2307: Не удается найти модуль "pkg" или связанные с ним объявления типов.
//     Существуют типы в "node_modules/pkg/lib/i.d.ts", но этот результат
//     не удалось разрешить с помощью текущей настройки "moduleResolution".
//     Рассмотрите возможность обновления до "node16", "nodenext" или "bundler".

// компилятор прямо называет лечение — редкий случай
console.log("типы есть, но резолвер до них не дошёл");

страница примера

Сначала предположите, что выведет код

В шестой версии история закончилась: node10, его синоним node и совсем древний classic объявлены нерекомендуемыми. Конфиг с ними падает ошибкой TS5107: Параметр "moduleResolution=node10" является нерекомендуемым и перестанет работать в TypeScript 7.0. — заглушить её можно только строкой "ignoreDeprecations": "6.0", и то до седьмой версии. Кстати, если написать "node", в тексте ошибки всё равно будет node10: компилятор переименовал значение и говорит новым именем.

Значение	Кому	Что важно
`nodenext`	код, который запускает сам Node	смотрит на `"type"` в `package.json` и на расширение файла; относительные пути требуют расширения
`bundler`	код, который собирает Vite, webpack, Next, esbuild	понимает `exports`, расширение не требует
`node10`, `node`	старые проекты	не знает про `exports`; с 6.0 ошибка, в 7.0 удалён
`classic`	никому	эпоха до `node_modules`; тоже нерекомендуем

Расширения — главная неожиданность при переезде на nodenext. Импорт "./user" перестаёт работать: TS2835 — Относительные пути импорта требуют явных расширений файлов при импорте ECMAScript, если "--moduleResolution" имеет значение "node16" или "nodenext". Вы хотели использовать "./user.js"? Именно .js, а не .ts: в строке импорта пишется имя файла, который получится после сборки. Написать "./user.ts" тоже нельзя — TS5097 попросит включить allowImportingTsExtensions.

Последнее, что стоит знать про эту пару настроек, — они связаны. При "module": "nodenext" компилятор требует такое же значение у moduleResolution или не требует ничего (TS5109), а bundler отказывается работать с nodenext вовсе (TS5095). Поэтому практика простая: задавайте module, а moduleResolution не трогайте вообще. С шестой версии незаданное значение означает bundler — а для nodenext подставится nodenext.

Код запускает Node — "module": "nodenext" и расширения .js в импортах. Код уходит в сборщик — "module": "preserve": компилятор оставит ваши импорты как есть, а разрешение само станет bundler. В обоих случаях строки moduleResolution в конфиге нет.

ts

// для Node:
//   { "compilerOptions": { "module": "nodenext", "verbatimModuleSyntax": true } }
// для сборщика:
//   { "compilerOptions": { "module": "preserve", "verbatimModuleSyntax": true } }
//
// module: preserve оставляет строку импорта нетронутой —
// ровно то, чего ждёт от TypeScript любой современный сборщик

console.log("конфиг из двух строк вместо пяти");

страница примера

Сначала предположите, что выведет код

Значение preserve заодно разрешает в одном файле и import, и require — удобно, пока проект переезжает. Полный разбор остальных полей конфига — в первой статье главы.

Имя в TypeScript живёт в двух пространствах: типов и значений. До выполнения доезжают только имена, у которых есть значение.
Компилятор сам вычёркивает из импорта то, что оказалось типом; если типами были все имена, исчезает вся строка — вместе с побочным эффектом соседнего файла.
import type { X } помечает весь список, import { type X } — одно имя; вторая форма при verbatimModuleSyntax оставляет пустой import {} и сохраняет загрузку модуля.
verbatimModuleSyntax запрещает догадки: непомеченный тип даёт TS1484, зато сборщик получает тот же результат, что и tsc. В новом проекте флаг включён по умолчанию.
node10, node и classic в шестой версии дают ошибку TS5107 и исчезнут в седьмой; живых значения два — nodenext для Node и bundler для сборщиков.
Задавайте module, а moduleResolution не трогайте: незаданное значение сегодня и есть bundler, а при nodenext подставится nodenext.

1/4Файл user.ts экспортирует интерфейс User и константу VERSION. В main.ts написано import { User } from "./user.js", и User используется только в аннотации. Флага verbatimModuleSyntax нет. Что окажется в собранном main.js?

2/4В файле написано import type { Session } from "./session.js", а ниже — const s = new Session(). Что произойдёт?

3/4В конфиге проекта стоит "moduleResolution": "node". Что скажет TypeScript 6.0?

4/4Проект собирается esbuild. Зачем ему verbatimModuleSyntax, если tsc и так умеет стирать импорты?

Расставить пометки

Соседний файл ./catalog.js экспортирует все четыре имени из примера ниже, и в проекте включён verbatimModuleSyntax. Напишите строку импорта так, чтобы компилятор не ругался, а в сборку попало только необходимое. Запустите пример: он подсказывает, у кого из имён есть значение.

ts

// в соседнем файле "./catalog.js" объявлено ровно это
interface Product {
  id: string;
}
type Sort = "price" | "name";
class Catalog {
  items: Product[] = [];
}
const PAGE_SIZE = 20;

// ваша строка: import { ... } from "./catalog.js";
function firstPage(sort: Sort): Product[] {
  const catalog = new Catalog();
  console.log("сортировка", sort, "по", PAGE_SIZE); // сортировка price по 20
  return catalog.items;
}
console.log(firstPage("price").length); // 0

страница примера

Сначала предположите, что выведет код

Смотрим не на объявление, а на использование. Sort стоит только в аннотации параметра, Product — только в типе возврата: оба существуют лишь в пространстве типов. Catalog зовётся через new, PAGE_SIZE печатается — это значения.

jsлистинг · не запускается

import { type Product, type Sort, Catalog, PAGE_SIZE } from "./catalog.js";

import { type Product, type Sort, Catalog, PAGE_SIZE } from "./catalog.js";

В сборке от строки останется import { Catalog, PAGE_SIZE } from "./catalog.js". Форма import type { ... } здесь не подходит: она пометила бы весь список, и new Catalog() сломался бы на TS1361. Обратите внимание, что Product внутри Catalog нас не касается — этот файл его не видит.

Не потерять побочный эффект

Файл theme.ts при загрузке применяет тему и заодно экспортирует тип. В main.ts из него берут только тип — и тема перестала применяться. Предложите два решения: одно опирается на флаг из статьи, второе работает при любых настройках.

ts

// theme.ts:  document.body.dataset.theme = "dark";  // побочный эффект файла
//            export type Theme = "dark" | "light";
// main.ts:   import { Theme } from "./theme.js";
//            const current: Theme = "dark";
//
// тема не применилась: строка импорта исчезла вместе с загрузкой theme.ts

type Theme = "dark" | "light";
const current: Theme = "dark";
console.log(current); // dark

страница примера

Сначала предположите, что выведет код

Первое решение — модификатор на отдельном имени. При включённом verbatimModuleSyntax строка не исчезает, а превращается в пустой импорт, и файл загружается.

jsлистинг · не запускается

import { type Theme } from "./theme.js";
// в сборке: import {} from "./theme.js";

import { type Theme } from "./theme.js";
// в сборке: import {} from "./theme.js";

Второе решение не зависит от настроек и честнее читается: побочный эффект просят отдельной строкой, а тип — своей.

jsлистинг · не запускается

import "./theme.js";
import type { Theme } from "./theme.js";

import "./theme.js";
import type { Theme } from "./theme.js";

Импорт без фигурных скобок стирать нечем: в нём нет ни одного имени, только требование загрузить файл. Второй вариант предпочтительнее ещё и потому, что намерение видно с первого взгляда — пустой import {} в сборке легко принять за мусор.

Конфиг из чужого проекта

Вам достался проект на TypeScript 5, который собирается Vite. Под шестой версией компилятор перестал запускаться. Что убрать и что оставить?

ts

// tsconfig.json из проекта:
//   {
//     "compilerOptions": {
//       "target": "es2022",
//       "module": "esnext",
//       "moduleResolution": "node",
//       "strict": true
//     }
//   }
//
// TS5107: Параметр "moduleResolution=node10" является нерекомендуемым
//         и перестанет работать в TypeScript 7.0

const slugify = (s: string): string => s.trim().toLowerCase().replace(/\s+/g, "-");
console.log(slugify("  Модули в TS  ")); // модули-в-ts

страница примера

Сначала предположите, что выведет код

Достаточно удалить строку moduleResolution целиком: с шестой версии незаданное значение означает bundler — ровно то, что нужно проекту на Vite. Заодно стоит поменять module на preserve, чтобы компилятор не переписывал импорты, и включить verbatimModuleSyntax.

jsлистинг · не запускается

{
  "compilerOptions": {
    "target": "es2022",
    "module": "preserve",
    "strict": true,
    "verbatimModuleSyntax": true
  }
}

{
  "compilerOptions": {
    "target": "es2022",
    "module": "preserve",
    "strict": true,
    "verbatimModuleSyntax": true
  }
}

Чего делать не стоит — дописывать "ignoreDeprecations": "6.0". Ошибка замолчит, но в седьмой версии значения не станет вовсе, и разговор повторится в худший момент. И не стоит менять node на nodenext: тогда компилятор потребует расширения .js во всех относительных импортах, а проекту на сборщике это не нужно.

Модули: import type, verbatimModuleSyntax, moduleResolution

Видеоразбор темы за 5–7 минут

Одно имя, два пространстваПочему импорт вообще приходится помечать

Стирание импортовКомпилятор вычёркивает из списка то, что оказалось типом

import typeДве формы записи и разная судьба у собранного файла

verbatimModuleSyntaxСборка повторяет вашу строку импорта слово в слово

moduleResolutionКак строка «./user.js» превращается в файл на диске

Итогошпаргалка по теме

Проверьте себявопросы по теме

Задачизадачи с решениями

Расставить пометки

Не потерять побочный эффект

Конфиг из чужого проекта