export и import

Модуль — обычный файл с кодом, но с одной особенностью: всё, что в нём объявлено, снаружи по умолчанию не видно. Наружу выходит только помеченное словом export, остальное остаётся внутренней кухней модуля.

Пометить можно прямо при объявлении — export const, export function, export class — или собрать список в конце файла: export { hi, NAME };. Второй способ удобен, когда хочется одним взглядом увидеть весь публичный список. Импорт перечисляет нужные имена в фигурных скобках, и они должны совпадать с экспортированными буква в букву.

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

// hi.js:   export const NAME = "Мир";
//          export function hi(who) { return "Привет, " + who + "!"; }
// main.js: import { hi, NAME } from "./hi.js";
const NAME = "Мир";
const hi = (who) => "Привет, " + who + "!";
console.log(hi(NAME));

const secret = 42;          // не экспортирован — снаружи его просто нет
const visible = secret * 2;
// export { visible };      // список экспорта в конце файла
console.log(visible);
console.log(typeof secret);

Если в файле одна главная сущность — класс, компонент, функция-обработчик, — её экспортируют как export default. Такой экспорт импортируется без фигурных скобок, и имя выбирает тот, кто импортирует: файл отдаёт значение, а не название.

// user.js:  export default class User { constructor(name) { this.name = name; } }
// main.js:  import Person from "./user.js";  // имя придумали сами
class User { constructor(name) { this.name = name; } }
const Person = User;
console.log(new Person("Аня").name);

default в модуле не больше одного, но он спокойно уживается с именованными экспортами в том же файле. У свободы имени есть обратная сторона: опечатку никто не заметит, один и тот же модуль в разных местах проекта окажется User, Person и u. Поэтому многие команды договариваются использовать только именованные экспорты.

Рано или поздно два модуля предложат одинаковое имя. Спасает слово as: import { format as formatDate } from "./date.js". Переименовать можно и на стороне экспорта — export { format as formatDate };, — но тогда имя выбирает автор модуля, а не тот, кто им пользуется.

// import { hi as sayHi } from "./hi.js";
const hi = (who) => "Привет, " + who + "!";
const sayHi = hi;  // as — это просто второе имя для того же значения
console.log(sayHi === hi);
console.log(sayHi("Кот"));

Когда имён много, их забирают одним махом: import * as math from "./math.js". Получается объект-пространство имён, где каждый именованный экспорт — свойство, а default лежит в свойстве default. Обращаться придётся через точку, зато сразу видно, из какого модуля приехала функция.

// import * as math from "./math.js";
const math = { PI: 3.14, square: (n) => n * n };
console.log(math.square(5));
console.log(Object.keys(math));

// counter.js: export let count = 0;   export function inc() { count += 1; }
// main.js:    import { count, inc } from "./counter.js";
let count = 0;
function inc() { count += 1; }
inc();
inc();
console.log(count);

Когда модулей становится десяток, неудобно помнить, что hi живёт в hi.js, а bye — в bye.js. Поэтому делают файл-витрину, обычно index.js, который ничего не придумывает сам, а пропускает чужое наружу: export { hi } from "./hi.js";.

Формы такие же гибкие, как у обычного экспорта: export { bye as farewell } from "./bye.js" переименует, export * from "./math.js" пропустит все именованные экспорты, export { default as Bye } from "./bye.js" вытащит default и даст ему имя. Внутренние файлы после этого можно свободно переставлять — снаружи виден только адрес витрины.

// index.js: export { hi } from "./hi.js";
//           export { bye as farewell } from "./bye.js";
const api = { hi: () => "Привет!", farewell: () => "Пока!" };
console.log(api.hi(), api.farewell());

export ... from — это не импорт: внутри самого index.js имя hi так и не появится. Нужно им пользоваться — импортируйте отдельной строкой.

import и export разрешены только на верхнем уровне файла, а путь обязан быть строкой-литералом: ни переменной, ни склейки, ни if вокруг. Такая жёсткость даёт главное — граф зависимостей известен ещё до того, как выполнится первая строка. Поэтому импорты «поднимаются»: модуль-сосед загрузится, даже если строка import стоит в самом низу файла.

// import { hi } from "./hi.js";
console.log(hi("Мир"));
function hi(who) { return "Привет, " + who + "!"; }

Из той же статичности растёт tree shaking. Сборщик читает исходники, не запуская их, и видит: из библиотеки на сто функций проект берёт три. Остальные девяносто семь в бандл не попадут. Форма импорта при этом почти не важна: import { debounce } from "lodash-es" и import * as _ с вызовом _.debounce() дают одинаковый бандл — esbuild и webpack видят, к какому свойству пространства имён обращается код. Важно другое: библиотека должна раскладывать код на отдельные экспорты, а не отдавать его одним большим объектом.

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

// вместо статичного import — выражение import(), оно возвращает промис
const load = () => Promise.resolve({ hi: () => "Привет!" });
load().then((m) => console.log(m.hi()));