Перечень loader-значений

Механизм loader в Esbuild определяет, каким образом конкретный файл будет интерпретирован на этапе сборки. Каждый loader задаёт стратегию обработки входного модуля: преобразование в JavaScript, инлайн как строка, выдача как URL-ресурс, передача в бинарном виде или полное игнорирование содержимого.

Loader-значения применяются как для расширений файлов, так и для отдельных путей через конфигурацию сборки. Поведение loader напрямую влияет на итоговый бандл, структуру зависимостей и способ включения ресурсов в приложение.

JavaScript и JSX

js

Loader js используется для стандартных JavaScript-файлов без JSX-синтаксиса. Файл передаётся в граф модулей без дополнительных трансформаций, кроме базовой обработки import/export.

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

  • сохраняется исходный синтаксис ES Modules;
  • возможна минимальная транспиляция для совместимости;
  • не применяется JSX-трансформация.

jsx

Loader jsx предназначен для JavaScript-файлов, содержащих JSX-выражения.

Поведение:

  • JSX преобразуется в вызовы React.createElement или автоматический JSX runtime (в зависимости от настройки);
  • файл остаётся JavaScript-модулем после трансформации;
  • используется в React-проектах и аналогичных UI-фреймворках.

TypeScript

ts

Loader ts обрабатывает TypeScript без JSX.

Характеристики:

  • удаление типов на этапе сборки;
  • отсутствие проверки типов (Esbuild не выполняет type-checking);
  • поддержка современных возможностей TS (enum, interface, generics).

tsx

Loader tsx объединяет поддержку TypeScript и JSX.

Особенности обработки:

  • удаление типов;
  • трансформация JSX;
  • итоговый результат — JavaScript-модуль;
  • применяется в React + TypeScript проектах.

JSON

json

Loader json позволяет импортировать JSON-файлы как модули.

Поведение:

  • содержимое JSON преобразуется в JavaScript-объект;
  • экспортируется как default export;
  • поддерживается tree-shaking на уровне ключей (ограниченно).

Пример использования:

import data from './config.json'

CSS

css

Loader css обрабатывает стили как часть графа модулей.

Поведение:

  • CSS объединяется в единый стильный бандл;
  • возможна минификация;
  • поддержка @import и URL-ресурсов;
  • результат обычно подключается через отдельный output или инъекцию в runtime.

Text

text

Loader text импортирует содержимое файла как строку.

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

  • файл преобразуется в JavaScript-строку;
  • сохраняются переносы и форматирование;
  • используется для шаблонов, markdown, SQL-запросов.

Пример:

import template from './template.txt'

Binary

binary

Loader binary позволяет импортировать файл как Uint8Array.

Поведение:

  • файл читается как сырые байты;
  • результат доступен в памяти как бинарный буфер;
  • используется для изображений, архивов, шрифтов в низкоуровневой обработке.

Base64

base64

Loader base64 преобразует файл в строку Base64.

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

  • бинарные данные кодируются в строку;
  • удобно для inline-встраивания ресурсов;
  • увеличивает размер бандла, но исключает внешние зависимости.

Data URL

dataurl

Loader dataurl конвертирует файл в Data URL формат.

Поведение:

  • результат содержит MIME-тип и base64-данные;
  • применяется для изображений и мелких ассетов;
  • позволяет использовать ресурсы без отдельного запроса.

File

file

Loader file перемещает файл в выходную директорию сборки и возвращает ссылку на него.

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

  • файл копируется без изменений;
  • возвращается URL-строка;
  • используется для изображений, шрифтов, медиафайлов;
  • поддерживает хеширование имени файла для кеширования.

Empty

empty

Loader empty полностью игнорирует содержимое файла.

Поведение:

  • модуль заменяется пустым объектом;
  • зависимости не включаются в бандл;
  • используется для условного исключения кода или заглушек.

Автоматический выбор loader

Esbuild может определять loader автоматически по расширению файла, если не указана явная настройка. Однако явное определение через конфигурацию build API или CLI обеспечивает предсказуемость результата.

Пример конфигурации:

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

Поведение loader в графе зависимостей

Каждый loader влияет не только на преобразование файла, но и на способ его включения в dependency graph:

  • текстовые loaders превращают файлы в строки и исключают их из рантайм-загрузки;
  • binary и base64 loaders увеличивают размер бандла, но упрощают доставку ресурсов;
  • file loader переносит ответственность за загрузку на браузер или runtime;
  • empty loader полностью обрывает цепочку зависимостей.

Loader и производительность сборки

Разные loader-значения по-разному влияют на скорость сборки:

  • js, ts и tsx требуют парсинга и трансформации AST;
  • json обрабатывается быстрее за счёт прямого парсинга;
  • text, base64, binary работают через файловое чтение без AST;
  • file практически не участвует в трансформации содержимого;
  • empty является наиболее дешёвым вариантом обработки.

Комбинирование loader с плагинами

Loader часто используется совместно с плагинами Esbuild для расширенной логики обработки:

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

Ограничения loader-модели

Модель loader в Esbuild предельно упрощена:

  • отсутствует многоступенчатая цепочка трансформаций;
  • один файл может иметь только один loader;
  • нет встроенной системы post-processing на уровне loader;
  • сложная логика переносится в плагины.

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

Оглавление