Динамический импорт

Статический import — часть скелета модуля: движок разбирает его ещё до выполнения кода. Поэтому путь обязан быть строковым литералом, а сама строка — стоять на верхнем уровне файла. import() устроен иначе: это выражение, которое выполняется в свой черёд и возвращает промис.

Промис разрешается объектом модуля — тем самым «пространством имён», где именованные экспорты лежат под своими именами, а export default — под ключом default. Пока промис не разрешился, никаких имён у вас нет: ни деструктуризации, ни вызовов.

const loading = import("./math.js"); // запрос уходит прямо сейчас
console.log(loading instanceof Promise);
loading.catch(() => console.log("модуль не найден"));

async function sum() {
  const { add, default: title } = await import("./math.js");
  return `${title}: ${add(2, 3)}`;
}
console.log(sum.constructor.name);

Типичная картина: на странице есть кнопка «Открыть редактор», а сам редактор весит больше, чем вся остальная страница. Пока кнопку не нажали, этот код — мёртвый груз в главном потоке.

С import() запрос за файлом уходит в момент клика. Первый клик подождёт сеть лишние доли секунды, зато страница показывается и начинает отвечать раньше — а это ровно то, что человек замечает.

async function openEditor() {
  const { createEditor } = await import("./editor.js"); // запрос уйдёт только здесь
  return createEditor();
}
// файл editor.js не тронут, пока никто не нажал кнопку
console.log(typeof openEditor);

Если фичей пользуется меньше половины людей — её место за import(). Остальное решают замеры, а не вкус.

Второй повод — код, который нужен не всем. Полифил для старых браузеров, языковой пакет, панель администратора, экспорт в PDF: всё это грузится по условию, вычисленному уже во время работы. Статический import так не умеет — он безусловен по определению.

Путь у import() — обычное выражение, поэтому его можно собрать из переменной или получить из другой функции.

function pickLocale(lang) {
  return lang === "ru" ? "./locales/ru.js" : "./locales/en.js";
}
console.log(pickLocale("ru"));
console.log(pickLocale("de"));
const loadLocale = (lang) => import(pickLocale(lang));
console.log(typeof loadLocale);

Сеть — вещь ненадёжная, и промис import() отклоняется, если файл не приехал. Ловите ошибку там же, где загружаете: страница обязана пережить отсутствие одной необязательной фичи.

async function withStats() {
  try {
    return (await import("./stats.js")).render();
  } catch {
    return "работаем без статистики";
  }
}
withStats().then(console.log);

Сборщик — webpack, Vite, esbuild — читает вызов import() как команду «режь тут». Всё, что достижимо только из динамического импорта, уезжает в отдельный чанк и в главный файл не попадает. Как именно идёт разрез, покажет самодельный сборщик в главе про сборку.

Выигрыш считается не в мегабайтах на диске, а во времени до момента, когда со страницей можно работать. Каждый килобайт JavaScript нужно скачать, разобрать и выполнить — и делается это в том же потоке, который рисует интерфейс.

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

let warm = null;
function warmUp() {
  warm ??= import("./chart.js").catch(() => null); // греем заранее, ошибку гасим
  return warm;
}
console.log(warmUp() === warmUp());

Сборщику нужно заранее понимать, какие файлы вообще могут понадобиться. С import(`./locales/${lang}.js`) он справится: видит фиксированный префикс и расширение, нарежет чанк на каждый файл в папке. А путь, склеенный из произвольной строки или пришедший с сервера, он проанализировать не может — такого чанка в сборке просто не окажется.

const lang = "ru";
console.log(`./locales/${lang}.js`);
// префикс ./locales/ и .js фиксированы — чанки нарежутся заранее
const loaders = ["ru", "en"].map((l) => () => import(`./locales/${l}.js`));
console.log(loaders.length, typeof loaders[0]);

Вторая ловушка — считать import() функцией. Это синтаксическая конструкция: её нельзя присвоить переменной, передать в map или вызвать через call. Нужен «загрузчик» как значение — заверните вызов в стрелку, как в примере выше.

И третье: путь считается от файла, в котором написан import(), а не от адреса страницы. Правило то же, что у статического импорта, но при вычисляемых путях о нём забывают чаще.