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

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

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

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

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:

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.