Декларации модулей

Atomico использует модульную систему ES Modules как основу для организации кода. Компоненты, хуки и вспомогательные функции оформляются как отдельные модули и импортируются в нужных местах. Такая архитектура обеспечивает оптимизацию бандла, минимизацию избыточных зависимостей и предсказуемость сборки.

Основные принципы модульности

1. Явный экспорт

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

2. Декларативный импорт

Импорты формируют структуру зависимостей. Atomico интегрируется с системой импортов браузера и инструментов сборки (Vite, Rollup, Webpack), сохраняя одинаковую семантику.

3. Независимость модулей

Компоненты не предполагают обязательного знания о месте использования. Локальные зависимости описываются через импорт, внешний контракт — через свойства и события.

Экспорт компонентов

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

Пример:

export default function MyButton() {
    return <button>Кнопка</button>;
}

Альтернативный подход:

export function MyButton() {
    return <button>Кнопка</button>;
}

Импорт атомарных модулей

Импорт компонента или функции определяет доступные зависимости:

import MyButton from "./button.js";

Именованный импорт обеспечивает более точный контроль:

import { useProp, useListener } from "atomico";

Использование именованных экспортов позволяет компоненту выбирать только необходимые хуки и утилиты.

Декларации модулей с хуками

Хуки формируют ядро реактивности Atomico. Их рекомендуется выделять в отдельные модули, что способствует разделению ответственности. Такая стратегия повышает переиспользуемость логики и снижает связанность компонентов.

Пример организации:

/hooks/use-toggle.js
export function useToggle(initial) {
    const [state, setState] = useState(initial);
    const toggle = () => setState(!state);
    return [state, toggle];
}
/components/toggle-button.js
import { useToggle } from "../hooks/use-toggle.js";

export function ToggleButton() {
    const [open, toggle] = useToggle(false);
    return <button oncl ick={toggle}>{open ? "Открыто" : "Закрыто"}</button>;
}

Декларации модулей и дерево зависимостей

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

  • анализ кода на уровне сборщика;
  • удаление неиспользуемых импортов (tree shaking);
  • динамический импорт;
  • предзагрузку критичных частей приложения.

Отдельные декларации типов и контрактов

При использовании TypeScript или JSDoc контракты компонентов и хуков оформляются в соответствующих декларациях. Это упрощает автодополнение, проверку типов и документацию.

Пример JSDoc над компонентом:

/**
 * @prop {string} label
 * @prop {boolean} disabled
 */
export function MyButton({ label, disabled }) {
    return <button disabled={disabled}>{label}</button>;
}

Такая декларация влияет на понимание API компонента инструментами разработки.

Динамические декларации модулей

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

const { ModalComponent } = await import("./modal.js");

Стратегия подходит для маршрутизации, ленивой загрузки тяжёлых компонентов и оптимизации интерактивных зон.

Поведение при сборке

Сборщики на основе ES Modules анализируют декларации модулей Atomico напрямую:

  • неиспользуемый код удаляется;
  • имена экспортов остаются предсказуемыми;
  • минимизация не нарушает структуру зависимостей;
  • поддерживается загрузка через <script type="module">.

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

Разделение деклараций состояния и представления

Использование хуков в отдельных модулях способствует разделению логики и JSX-разметки. Компонент остаётся тонким слоем, связывающим состояние с DOM. Такая организация даёт возможность переиспользования состояния в разных компонентах и тестирования логики без рендера.

Инкапсуляция и открытая API-сема

Модуль объявляет только те сущности, которые задумываются как часть API. Всё остальное остаётся внутренним. Это позволяет поддерживать стабильные контракты, даже при изменении внутреннего устройства компонентов.

Ключевые моменты:

  • экспорт — явное API;
  • отсутствие экспорта — внутренний код;
  • хуки и утилиты могут образовывать скрытые модули.

Модульные декларации и расширяемость

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

  • базовые утилиты и хуки;
  • примитивы UI;
  • комплексные компоненты;
  • модули интеграции (маршрутизация, сервисы, тема).

Каждый уровень формирует собственные декларации модулей. Такая структура облегчает развитие библиотек и интеграцию в существующие интерфейсы.

Выводы для архитектуры проектов на Atomico

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

Оглавление