Обработка JSON, YAML, TOML как модулей

Parcel рассматривает любые подключаемые файлы как часть единого графа зависимостей, где JSON, YAML и TOML превращаются в полноценные модули наравне с JavaScript. Это позволяет использовать конфигурационные форматы напрямую в коде без ручного парсинга и промежуточных преобразований. Такой подход снижает количество шаблонного кода и делает структуру проекта более декларативной.

Внутри сборщика каждый импортируемый файл проходит через цепочку трансформаций и превращается в asset — абстракцию модуля с нормализованным интерфейсом. Независимо от исходного формата (JS, JSON, YAML, TOML), итогом становится модуль, который:

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

Это делает работу с конфигурационными форматами частью стандартного JavaScript-пайплайна.

JSON как нативный модуль

JSON является встроенной поддержкой Parcel и не требует дополнительной настройки. Любой .json файл автоматически интерпретируется как модуль.

{
  "appName": "DemoApp",
  "version": "1.0.0",
  "debug": true
}

Импорт выполняется напрямую:

import config from './config.json';

console.log(config.appName);

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

Parcel применяет к JSON следующие правила:

  • файл парсится один раз и кэшируется
  • экспортируется как default export
  • поддерживается tree-shaking на уровне ключей при оптимизации
  • изменения в JSON триггерят точечную пересборку зависимых модулей

JSON становится частью ESM-графа, несмотря на отсутствие собственных экспортов.

YAML как модуль через трансформер

YAML не входит в базовую поставку Parcel, но поддерживается через трансформер @parcel/transformer-yaml. После установки и настройки YAML-файлы становятся импортируемыми модулями.

Установка:

npm install @parcel/transformer-yaml

Пример YAML-файла:

app:
  name: DemoApp
  features:
    auth: true
    payments: false

Импорт:

import config from './config.yaml';

console.log(config.app.name);

Поведение трансформации YAML

При обработке Parcel:

  • парсит YAML в AST-структуру
  • преобразует результат в JavaScript-объект
  • экспортирует через export default
  • сохраняет структуру вложенных объектов без изменений

Важная особенность — YAML поддерживает сложные структуры (ссылки, anchors), которые преобразуются в обычные JS-объекты до этапа сборки.

TOML как конфигурационный модуль

TOML также подключается через отдельный трансформер @parcel/transformer-toml.

Установка:

npm install @parcel/transformer-toml

Пример TOML-файла:

title = "DemoApp"

[server]
host = "localhost"
port = 8080

Импорт в Jav * aScript:

import config from './config.toml';

console.log(config.server.port);

Особенности TOML-интеграции

Parcel обрабатывает TOML следующим образом:

  • использует строгий синтаксический парсер формата TOML
  • преобразует секции [section] в вложенные объекты
  • поддерживает типы: строки, числа, булевы значения, массивы
  • результат всегда приводится к чистому JSON-подобному объекту

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

Объединение конфигурационных форматов в одном графе

Parcel позволяет одновременно использовать JSON, YAML и TOML в рамках одного проекта без дополнительных адаптеров.

import jsonConfig from './config.json';
import yamlConfig from './config.yaml';
import tomlConfig from './config.toml';

export const config = {
  ...jsonConfig,
  ...yamlConfig.app,
  server: tomlConfig.server
};

Все три формата:

  • попадают в единый dependency graph
  • обрабатываются через разные трансформеры
  • приводятся к унифицированному JS-объекту
  • кешируются независимо друг от друга

Кэширование и инкрементальная сборка

Одно из ключевых свойств Parcel — агрессивное кэширование на уровне контента. Для JSON/YAML/TOML это особенно эффективно, так как:

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

В результате конфигурационные файлы практически не влияют на время полной пересборки проекта.

Типизация и взаимодействие с TypeScript

При использовании TypeScript JSON автоматически поддерживает типизацию через resolveJsonModule. Для YAML и TOML типы обычно описываются вручную или генерируются:

declare module "*.yaml" {
  const value: any;
  export default value;
}

declare module "*.toml" {
  const value: any;
  export default value;
}

Parcel не навязывает схему типов, но гарантирует консистентное преобразование в runtime-объект.

Ошибки парсинга и диагностика

При некорректной структуре файлов Parcel:

  • останавливает сборку на этапе трансформации
  • указывает точное место ошибки (строка, колонка)
  • отображает исходный файл без промежуточных искажений

Типичные ошибки:

  • синтаксическая ошибка YAML (неправильные отступы)
  • нарушение TOML-структуры секций
  • невалидный JSON (лишние запятые, кавычки)

Диагностика выполняется до этапа бандлинга, что упрощает отладку конфигураций.

Производительность при работе с конфигурациями

Parcel оптимизирует работу с JSON/YAML/TOML за счёт:

  • ленивого парсинга (только при необходимости)
  • параллельной трансформации модулей
  • переиспользования AST при повторных сборках
  • минимизации промежуточных представлений

Даже при большом количестве конфигурационных файлов влияние на сборку остаётся минимальным.

Встраивание конфигураций в бизнес-логику

Конфигурационные форматы в Parcel часто используются как источник runtime-данных:

import routes from './routes.yaml';

routes.forEach(route => {
  console.log(route.path);
});

или:

import settings from './app.toml';

if (settings.debug) {
  console.log('Debug mode enabled');
}

Такой подход устраняет необходимость ручного чтения файлов через fs и парсинга в runtime.

Гибридные сценарии использования

В реальных проектах часто применяется комбинирование форматов:

  • JSON — для статичных данных и совместимости
  • YAML — для читаемых конфигураций
  • TOML — для строго структурированных настроек

Parcel объединяет их в один механизм импорта, сохраняя единообразие интерфейса и поведения модулей во всём проекте.

Оглавление