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

Незалежно від того, чи клонуєте ви вихідний код з 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.