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

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

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

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

my-nocobase-app/
├── packages/              # Исходный код проекта
│   ├── plugins/           # Плагины в разработке (без компиляции)
├── storage/               # Данные времени выполнения и динамически генерируемый контент
│   ├── apps/
│   ├── db/
│   ├── logs/
│   ├── uploads/
│   ├── plugins/           # Скомпилированные плагины (включая загруженные через UI)
│   └── tar/               # Файлы пакетов плагинов (.tar)
├── scripts/               # Вспомогательные скрипты и инструментальные команды
├── .env*                  # Конфигурации переменных окружения для разных сред
├── lerna.json             # Конфигурация workspace в Lerna
├── package.json           # Конфигурация корневого пакета, объявляет workspace и scripts
├── 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/: упакованные плагины, загруженные через UI или импортированные через CLI.
• tar/: сжатые пакеты плагинов, созданные после выполнения yarn build <plugin> --tar.

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

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

• .env, .env.test, .env.e2e: используются соответственно для локального запуска, модульного/интеграционного тестирования и сквозного тестирования.
• scripts/: хранятся общие скрипты обслуживания (например, инициализация базы данных, утилиты релиза и т. д.).

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

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

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

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

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

Создание плагина через CLI:

yarn pm create @my-project/plugin-hello

Сгенерированная структура каталогов:

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.