Быстрый старт фронтенда (headless)

«Headless» значит, что Pano ведёт данные, аккаунты и плагины сайта, а страницы рисует ваш собственный код. Начните с двух команд.

Две команды

Pano должен работать (здесь на http://localhost:8088). Сначала создайте ключ фронтенда (в панели: «Ключ подключения сайта»): Внешний вид -> Темы -> кнопка шестерёнки (Настройки показа сайта) -> Ключи подключения сайта -> Настроить -> Создать ключ (пока выбрано «Тема», эта строка не показывается; сначала выберите другой вариант), и сохраните строки .env, которые он покажет.

bunx @panomc/client-gen new my-site --url http://localhost:8088
cd my-site && bun run dev

Первая команда копирует стартовый шаблон SvelteKit, пишет .env и устанавливает зависимости. Вставьте ключ в .env:

API_URL=http://localhost:8088/api
PANO_FRONTEND_KEY=pfk_...
PANO_SITE_URL=http://localhost:5173

Без ключа публичные страницы (записи, магазин) работают; вход и регистрация просят создать ключ.

Шаблон это BFF: каждый вызов Pano делает его сервер, токен сессии лежит в HttpOnly-куки, а через прокси /pano он уже подключён к типизированному клиенту и виджетам.

Режимы фронтенда

Выберите в Внешний вид -> Темы -> кнопка шестерёнки (Настройки показа сайта) в разделе «Что должны видеть посетители?»:

Вариант (значение режима)	Что работает	Когда
Тема (THEME)	Тема Pano, запущенная Pano	Обычный сайт
Загруженный мной сайт (CUSTOM_APP)	Ваш zip, запущенный Pano	Свой сайт, но хостит его Pano
Мой сайт на другом сервере (EXTERNAL)	Ничего; Pano пересылает / на ваш адрес	Сайт работает в другом месте
Без сайта (NONE)	Ничего; только панель и API	Только серверы или полностью отдельный сайт

Загруженный мной сайт: bun run package в шаблоне, загрузите zip («Загрузить сайт (.zip)»), выберите его. В корне zip нужны manifest.json и index.js:

{ "id": "my-site", "type": "custom-app", "title": "My site", "version": "1.0.0", "author": "me" }

Bun.serve({ port: process.env.PORT, hostname: process.env.HOST, fetch: () => new Response('hello') });

Pano передаёт PORT, HOST, API_URL, PANO_API_URL, PANO_FRONTEND_KEY, PANO_SITE_URL, PROTOCOL_HEADER, HOST_HEADER. Мой сайт на другом сервере: введите адрес в поле «Адрес, где работает ваш сайт» (например http://127.0.0.1:4000; остальные поля: «Адрес, который видят посетители» и «Файл со списком страниц (необязательно)») и задайте в приложении ORIGIN равным публичному адресу Pano.

/panel, /api и /_pano всегда остаются у Pano. Переключаться обратно безопасно: если новый фронтенд не запустился, предыдущий продолжает работать.

Резервные страницы

Pano отправляет посетителям ссылки: письма активации, сброс пароля, возврат после оплаты. В вашем фронтенде этих страниц может ещё не быть, поэтому Pano отдаёт простые страницы под /_pano/<цель>:

Цель	Страница
auth.activate, auth.activate-new-email, auth.renew-password	Ссылки из писем
auth.login	Вход
market.order	Возврат после оплаты, статус заказа

Они существуют, пока вы не возьмёте цель на себя.

Карта URL

У каждой ссылки, которую строит Pano, есть имя цели. Порядок разрешения, побеждает первое совпадение:

1. Переопределение, заданное вами в Внешний вид -> Темы -> кнопка шестерёнки (Настройки показа сайта) -> Страницы, на которые ссылается Pano -> Настроить (PUT /api/v1/panel/frontend/urls).
2. urls из манифеста или дескриптора вашего фронтенда. false значит «такой страницы нет».
3. В режиме темы собственный маршрут темы для этой страницы.
4. Резервная страница /_pano/<цель>, если она есть; иначе ссылка опускается.

Прочитайте результат:

curl http://localhost:8088/api/v1/frontend/urls

Возьмите две цели в manifest.json своего приложения:

{ "urls": { "auth.activate": "/welcome/confirm?token={token}", "market.order": "/shop/o/{id}" } }

Серверный фронтенд на другом домене должен брать цели, начинающие сессию (createsSession): панель помечает их как «нужны серверным фронтендам».

Форма настроек

Фронтенд может описать свои настройки (settingsSchema с fields); GET /api/v1/frontend/settings вернёт значения. Типы полей: text, textarea, boolean, number, select, color, url, image.