---
title: "TeqFW: организация верхнего уровня кода"
description: "Почему плагины TeqFW разделяют исходники на Back, Front и Shared и как это помогает безопасно использовать ES-модули в браузере и Node.js."
date: 2024-02-15
---

TeqFW позволяет использовать часть JavaScript-кода без изменений и на
сервере, и в браузере — например, константы и DTO. Но фронтенд и бэкенд
решают разные задачи: фронтенд взаимодействует с человеком, бэкенд — с
базами, очередями и другими приложениями. Поэтому границы нужно сделать
очевидными уже в структуре пакета.

## Три области исходников

В обычном npm-пакете это могло бы выглядеть так:

    src/
      back/
      front/
      shared/

TeqFW использует CamelCase в именах каталогов и файлов:

    src/
      Back/
      Front/
      Shared/
        Dto/
          UserAuth/

**Back** содержит только серверный код; **Front** — только браузерный;
**Shared** — код, пригодный в обеих средах. Если в пакете нет кода одной
области, соответствующий каталог не нужен.

## Имена модулей и DI

По пути к ES-модулю TeqFW формирует логическое имя, которым оперирует
контейнер зависимостей. Например, файл
`src/Shared/Dto/UserAuth/Permission.js` может получить имя:

    Vendor_App_Shared_Dto_UserAuth_Permission

Контейнер использует такое имя для адресации и внедрения зависимости.
Разделение каталогов помогает одновременно читать архитектуру глазами и
сохранять одинаковый механизм связи для модулей.

## Почему это обязательное правило

Платформа отдаёт браузеру исходники из `Front` и `Shared`. Значит, в них
нельзя помещать зависимости, которые доступны только в Node.js.
Например:

``` js
import { existsSync, mkdirSync, rmSync } from 'node:fs';
```

Браузер не умеет выполнять API файловой системы Node.js. Такой импорт
законен в `Back`, но сломает загрузку в клиенте. Граница на верхнем
уровне пакета предотвращает эту ошибку раньше, чем она попадёт к
пользователю.

Примеры пакетов с этой структурой:
[demo-webauthn-pubkey](https://github.com/flancer64/demo-webauthn-pubkey/tree/main/src),
[spa-remote-console](https://github.com/flancer64/spa-remote-console/tree/main/src)
и [teqfw/core](https://github.com/teqfw/core/tree/main/src).

## Вывод

Корневой каталог можно назвать `src`, `source` или иначе. Но для
Teq-плагина разделение на `Back`, `Front` и `Shared` обязательно. Внутри
этих областей структура свободна, а на верхнем уровне правило фиксирует
сферы использования модуля и делает общий JavaScript между браузером и
Node.js управляемым.