Разработка фронтенда

Фронтенд Pano разделен на несколько проектов SvelteKit. Хотя они разрабатываются независимо, в конечном итоге они упаковываются вместе в основной JAR.

ПРЕДВАРИТЕЛЬНОЕ УСЛОВИЕ: РАБОТАЮЩИЙ БЭКЕНД

Прежде чем приступить к разработке фронтенда, у вас обязательно должен быть запущен бэкенд Pano.

• Только разработка фронтенда: Загрузите последнюю версию Pano .jar из наших Релизов.
• Full-Stack разработка: Если вы планируете изменять и бэкенд, пожалуйста, следуйте руководству по Разработке бэкенда, чтобы запустить его из исходного кода.

Технологический стек

• Фреймворк: SvelteKit
• Стили: Bootstrap 5 + SASS
• Среда выполнения: Bun (Быстрая среда выполнения JavaScript)
• Язык: JavaScript (Чистый JS обязателен. Мы верим, что с чистым JS возможен лучший мир!)

Философия языка (JavaScript против TypeScript)

В проекте Pano у нас есть четкая позиция по выбору языка:

• Всегда используйте JavaScript: Мы стремимся к тому, чтобы все было просто и легковесно.
• Никакого TypeScript: Мы избегаем TypeScript для обеспечения высокой совместимости и простоты.
• Почему?: Мы верим, что с чистым и хорошо написанным Vanilla JS возможен более эффективный и лучший мир. TypeScript не принимается в наших фронтенд-проектах.

Производительность и SEO

Pano использует возможности SvelteKit для обеспечения гибридного интерфейса SSR (Server-Side Rendering) и CSR (Client-Side Rendering).

• Фокус на SEO: Мы уделяем большое внимание SEO-оптимизации. Используя SSR, мы гарантируем, что весь контент легко индексируется поисковыми системами.
• Плавный UX: CSR используется для динамических взаимодействий, обеспечивая быстрый и плавный пользовательский опыт без полной перезагрузки страниц.

ОТВЕТСТВЕННОСТЬ РАЗРАБОТЧИКА

При разработке фронтенд-компонентов вы должны убедиться, что они совместимы с SSR. Избегайте прямого доступа к window или document вне жизненного цикла Svelte onMount. Всегда используйте семантический HTML для поддержания наших стандартов SEO.

• vanilla-theme: Встроенная эталонная (системная) тема, поставляемая вместе с Pano. Это не стартовый шаблон — новые темы создаются командой bunx @panomc/theme-core new.

Клонирование и подмодули

Наши темы и panel-ui содержат движок theme-core в виде git-подмодуля theme-core (этот репозиторий публикует как @panomc/theme-core, так и @panomc/sdk). setup-ui и website не требуют подмодуля — они используют @panomc/sdk напрямую из npm.

Рекомендуемый метод клонирования

Для проектов, содержащих подмодуль (темы, panel-ui), используйте флаг --recursive, чтобы получить и движок:

git clone https://github.com/PanoMC/panel-ui.git --recursive

Если вы уже клонировали обычным способом

Если вы пропустили флаг --recursive, инициализируйте и обновите подмодуль вручную:

git submodule update --init

Репозитории тем в основном генерируются: маршруты, мосты (bridges) и языковые файлы создаются командой theme-core sync, поэтому автор темы редактирует только theme.config.js, tokens.scss, src/views/ и lang-overrides/. Чтобы начать, см. Руководство по разработке тем.

Руководство по разработке

После клонирования репозитория и подмодулей выполните следующие шаги:

1. Установка

Установите зависимости с помощью Bun:

bun i

2. Запуск для разработки

Запустите сервер разработки:

bun dev

3. Порты и доступ

Каждый интерфейс работает на определенном порту. Не меняйте эти порты и убедитесь, что они свободны в вашей системе.

Интерфейс	Порт	Условие
setup-ui	3002	Установка не должна быть завершена.
vanilla-theme	3000	Установка должна быть завершена.
panel-ui	3001	Установка должна быть завершена.

ВАЖНОЕ ПРИМЕЧАНИЕ ПО ДОСТУПУ

• Нет прямого доступа: Вы не можете получить доступ к этим портам напрямую через браузер. Они обслуживаются через прокси Pano.
• Автоматическое перенаправление: При попытке ручного доступа к портам UI вы можете быть автоматически перенаправлены на http://localhost:8088 (порт бэкенда Pano по умолчанию).
• Вход администратора: Чтобы получить доступ к panel-ui через маршрут /panel, вы должны войти в систему как Администратор, используя учетные данные, определенные вами во время процесса установки.

Процесс упаковки

1. Каждый проект пользовательского интерфейса собирается и сжимается в .zip файл.
2. В процессе сборки Pano эти ZIP-архивы загружаются и встраиваются в итоговый JAR.
3. Во время работы Pano извлекает их в директорию ui/ и обслуживает с помощью Bun как микросервис.

Система UI аддонов

Вы можете создавать аддоны, которые добавляют функции в Панель или Темы.

• Backend-часть: Определяется как JAR-плагин.
• Frontend-часть: Разрабатывается на Svelte и помещается в папку plugins/.

Разработка UI аддонов

Для быстрого тестирования изменений интерфейса:

1. Поместите файлы вашего аддона в директорию plugins/ вашей установки Pano.
2. Включите Dev Mode в Панель -> Настройки.
3. Используйте команду bun dev, чтобы мгновенно видеть изменения (HMR).

---

Есть вопросы по интеграции Svelte? Спрашивайте в Discord!