# Структура проекта

Независимо от того, клонируете ли вы исходный код из Git или инициализируете проект с помощью `create-nocobase-app`, сгенерированный проект NocoBase по сути является монорепозиторием, основанным на **Yarn Workspace**.

## Обзор каталогов верхнего уровня

В следующем примере `my-nocobase-app/` используется как корневой каталог проекта. В разных средах могут быть небольшие отличия:

```bash
my-nocobase-app/
├── packages/              # Исходный код проекта
│   ├── plugins/           # Исходный код разрабатываемых плагинов (нескомпилированный)
├── storage/               # Данные времени выполнения и динамически генерируемый контент
│   ├── apps/
│   ├── db/
│   ├── logs/
│   ├── uploads/
│   ├── plugins/           # Скомпилированные плагины (включая загруженные через интерфейс)
│   └── tar/               # Файлы пакетов плагинов (.tar)
├── scripts/               # Вспомогательные скрипты и утилиты
├── .env*                  # Конфигурация переменных для различных сред
├── lerna.json             # Конфигурация рабочего пространства Lerna
├── package.json           # Конфигурация корневого пакета, объявляет рабочее пространство и скрипты
├── tsconfig*.json         # Конфигурации TypeScript (фронтенд, бэкенд, сопоставление путей)
├── vitest.config.mts      # Конфигурация модульных тестов Vitest
└── playwright.config.ts   # Конфигурация E2E-тестов Playwright
```

## Описание подкаталога packages/

Каталог `packages/` содержит основные модули NocoBase и расширяемые пакеты. Его содержимое зависит от источника проекта:

- **Проекты, созданные с помощью `create-nocobase-app`**: По умолчанию содержат только `packages/plugins/`, где хранится исходный код пользовательских плагинов. Каждый подкаталог является независимым npm-пакетом.
- **Клонированный официальный репозиторий исходного кода**: Вы увидите больше подкаталогов, таких как `core/`, `plugins/`, `pro-plugins/`, `presets/` и т.д., которые соответствуют ядру фреймворка, встроенным плагинам и официальным предустановленным решениям.

В любом случае, `packages/plugins` является основным местом для разработки и отладки пользовательских плагинов.

## Каталог storage/ для данных времени выполнения

В `storage/` хранятся данные, генерируемые во время выполнения, и результаты сборки. Ниже приведено описание распространенных подкаталогов:

- `apps/`: Конфигурация и кэш для сценариев с несколькими приложениями.
- `logs/`: Журналы выполнения и вывод отладки.
- `uploads/`: Загруженные пользователями файлы и медиаресурсы.
- `plugins/`: Упакованные плагины, загруженные через интерфейс или импортированные через CLI.
- `tar/`: Сжатые пакеты плагинов, сгенерированные после выполнения `yarn build <plugin> --tar`.

> Обычно рекомендуется добавлять каталог `storage` в `.gitignore` и обрабатывать его отдельно при развертывании или резервном копировании.

## Конфигурация среды и скрипты проекта

- `.env`, `.env.test`, `.env.e2e`: Используются для локального запуска, модульного/интеграционного тестирования и сквозного (E2E) тестирования соответственно.
- `scripts/`: Содержит часто используемые скрипты для операций (например, инициализация базы данных, вспомогательные инструменты для выпуска и т.д.).

## Пути загрузки плагинов и их приоритет

Плагины могут находиться в нескольких местах. При запуске NocoBase загружает их в следующем порядке приоритета:

1. Версия исходного кода в `packages/plugins` (для локальной разработки и отладки).
2. Упакованная версия в `storage/plugins` (загруженная через интерфейс или импортированная через CLI).
3. Пакеты зависимостей в `node_modules` (установленные через npm/yarn или встроенные во фреймворк).

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

## Шаблон каталога плагина

Создание плагина с помощью CLI:

```bash
yarn pm create @my-project/plugin-hello
```

Сгенерированная структура каталогов выглядит следующим образом:

```bash
packages/plugins/@my-project/plugin-hello/
├── dist/                    # Результаты сборки (генерируются по мере необходимости)
├── src/                     # Каталог исходного кода
│   ├── client/              # Код фронтенда (блоки, страницы, модели и т.д.)
│   │   ├── plugin.ts        # Основной класс клиентского плагина
│   │   └── index.ts         # Точка входа клиентской части
│   ├── locale/              # Многоязычные ресурсы (общие для фронтенда и бэкенда)
│   ├── swagger/             # Документация OpenAPI/Swagger
│   └── server/              # Код бэкенда
│       ├── collections/     # Определения коллекций
│       ├── commands/        # Пользовательские команды
│       ├── migrations/      # Скрипты миграции базы данных
│       ├── plugin.ts        # Основной класс серверного плагина
│       └── index.ts         # Точка входа серверной части
├── index.ts                 # Экспорт для связи фронтенда и бэкенда
├── client.d.ts              # Объявления типов фронтенда
├── client.js                # Артефакт сборки фронтенда
├── server.d.ts              # Объявления типов бэкенда
├── server.js                # Артефакт сборки бэкенда
├── .npmignore               # Конфигурация игнорирования при публикации
└── package.json
```

> После завершения сборки каталог `dist/` и файлы `client.js`, `server.js` будут загружены при включении плагина.  
> На этапе разработки вам нужно изменять только каталог `src/`. Перед публикацией выполните `yarn build <plugin>` или `yarn build <plugin> --tar`.