Загрузчики (loaders): назначение и перечень

Загрузчики в Esbuild определяют способ интерпретации и трансформации импортируемых модулей, не являющихся «чистым» JavaScript. Любой импорт в проекте проходит через механизм разрешения и обработки, где загрузчик задаёт стратегию преобразования исходного файла в модуль, пригодный для включения в граф зависимостей.

Ключевая роль загрузчиков заключается в том, чтобы унифицировать работу с разнородными типами ресурсов: кодом на TypeScript, JSX-разметкой, стилями, JSON-данными, текстовыми файлами, бинарными ресурсами и ассетами. Вместо ручной обработки каждого типа файлов Esbuild применяет декларативную модель: для расширения файла назначается конкретный loader, который определяет результат импорта.

Каждый файл, попадающий в процесс сборки, сопоставляется с загрузчиком по двум основным механизмам:

  • по расширению файла (через настройку loader)
  • по явному указанию в конфигурации или CLI

После определения загрузчика Esbuild применяет соответствующую стратегию трансформации:

  • преобразование в JavaScript-код
  • преобразование в строку
  • преобразование в base64
  • копирование в выходной каталог с генерацией URL
  • интерпретация как JSON-модуля

Результатом работы загрузчика всегда является валидный модуль, который может быть включён в итоговый бандл.

loader: js

Загрузчик js является базовым вариантом обработки JavaScript-файлов. Он предполагает, что входной файл уже является корректным JavaScript-кодом без дополнительной трансформации синтаксиса.

Особенности:

  • отсутствует транспиляция
  • поддерживаются ES Modules
  • применяется к .js файлам по умолчанию

Поведение:

import util from "./util.js";

Файл передаётся в граф зависимостей без изменения структуры.

loader: jsx

Загрузчик jsx предназначен для обработки файлов с JSX-синтаксисом.

Назначение:

  • преобразование JSX-выражений в JavaScript
  • поддержка React-подобных конструкций

Пример:

const element = <div>Hello</div>;

После обработки:

const element = React.createElement("div", null, "Hello");

Трансформация зависит от настроек JSX runtime, но базовая задача loader — убрать JSX-синтаксис.

loader: ts

Загрузчик ts используется для файлов TypeScript без JSX.

Функции:

  • удаление типов
  • преобразование TypeScript в JavaScript
  • сохранение логики исполнения

Пример:

function sum(a: number, b: number): number {
  return a + b;
}

После обработки:

function sum(a, b) {
  return a + b;
}

Важно, что Esbuild не выполняет полную типовую проверку — он только удаляет аннотации типов.

loader: tsx

tsx объединяет поведение ts и jsx.

Применяется для:

  • TypeScript с JSX-разметкой
  • React + TypeScript проектов

Пример:

const App = () => <span>Text</span>;

Результат включает:

  • удаление типов
  • трансформацию JSX

loader: json

Загрузчик json позволяет импортировать JSON-файлы как JavaScript-объекты.

Поведение:

{
  "name": "app",
  "version": "1.0"
}

Импорт:

import data from "./config.json";

Результат:

const data = {
  name: "app",
  version: "1.0"
};

JSON становится статическим объектом, доступным во время выполнения.

loader: text

Загрузчик text интерпретирует содержимое файла как строку.

Использование:

  • шаблоны
  • markdown
  • любые текстовые ресурсы

Пример:

Hello world

Импорт:

import message from "./message.txt";

Результат:

const message = "Hello world\n";

Содержимое не парсится, а передаётся как строковый литерал.

loader: base64

Загрузчик base64 преобразует содержимое файла в строку base64.

Применение:

  • изображения
  • небольшие бинарные файлы
  • встроенные ресурсы

Пример:

import icon from "./icon.png";

Результат:

const icon = "data:image/png;base64,iVBORw0KGgo...";

Файл кодируется и встраивается прямо в бандл.

loader: binary

Загрузчик binary предоставляет доступ к файлу в виде бинарного массива.

Поведение:

  • содержимое представляется как Uint8Array
  • используется для низкоуровневой работы с данными

Пример:

import data from "./file.bin";

Результат:

const data = new Uint8Array([137, 80, 78, 71, ...]);

loader: file

Загрузчик file не инлайнит содержимое, а переносит файл в выходной каталог.

Особенности:

  • файл копируется в dist-папку
  • импорт возвращает URL строку
  • используется для крупных ассетов

Пример:

import image from "./photo.jpg";

Результат:

const image = "/assets/photo-8f3a2c.jpg";

Такой подход снижает размер бандла и позволяет работать с внешними ресурсами.

Поведение загрузчиков в цепочке сборки

Загрузчики работают на ранней стадии пайплайна, до этапа оптимизации и минификации. Их результат влияет на:

  • структуру модулей
  • размер итогового бандла
  • возможность tree-shaking
  • стратегию кеширования ассетов

Каждый файл проходит ровно один загрузчик, выбранный по конфигурации. Ошибочный выбор loader приводит к некорректной интерпретации содержимого.

Конфигурация и сопоставление расширений

В Esbuild загрузчики задаются через объект:

loader: {
  ".js": "js",
  ".jsx": "jsx",
  ".ts": "ts",
  ".tsx": "tsx",
  ".json": "json",
  ".txt": "text",
  ".png": "file"
}

Сопоставление расширений позволяет гибко управлять поведением сборки без изменения исходного кода.

Влияние загрузчиков на архитектуру проекта

Выбор загрузчиков определяет модель работы с ресурсами:

  • статические данные (json, text) превращаются в часть бандла
  • медиафайлы (file, base64) управляют стратегией доставки ассетов
  • исходный код (js, ts, jsx, tsx) задаёт уровень трансформации

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

Оглавление