Свій проєкт на шаблоні

Ця сторінка про те, як перетворити шаблон на ваш продукт: що перейменувати, де змінити інтерфейс, як додати свій домен і що робити з інтеграціями, які вам не потрібні. Як влаштовано процес роботи в самому репозиторії шаблону (feature_list.json, гілки, Definition of Done), описано окремо в Процесі роботи.

Перед читанням

• Проєкт запущено і пройдено перший сценарій.
• Пройдено Перший маршрут, бажано й Як додати фічу.

Що вже є: галерея

Перш ніж щось видаляти чи переписувати, подивіться, що ви отримуєте одразу. Усі скриншоти зроблено на чистому запуску з demo-акаунтами (db:seed --demo).

Вхід і реєстрація. Email і пароль, кнопки входу через Google і Facebook, скидання пароля. За ними стоять маршрути /api/auth/* і /api/auth/oauth/*.

Акаунт. Зміна пароля, прив'язка телефону й email, тема, розмір шрифту, кольорові схеми. Аватар завантажується в S3.

Адмінка: користувачі. Список з фільтром за id і датою реєстрації (GET /api/admin/users), доступний лише ролі admin.

Адмінка: хто онлайн. Оновлюється в реальному часі через WebSocket: коли хтось входить, рядок з'являється без перезавантаження.

Адмінка: база знань. Статті для AI-чату підтримки, переіндексація, початкове наповнення.

Чат підтримки. AI відповідає на основі бази знань, відповідь приходить частинами через WebSocket. Потрібен OPENAI_API_KEY (без нього кнопка показує Failed to open support chat).

Для ручного виклику будь-якого HTTP- чи WS-маршруту є окремий застосунок API Playground.

1. Перейменувати

Назва шаблону зашита в кількох місцях. Нижче список, зібраний пошуком Vibe Template, VIBE і vibe-template по packages/ (без тестів і node_modules):

Що	Де
Назва workspace	package.json ("name": "vibe-template")
Заголовок і опис сторінки	packages/frontend/index.html (<title>, meta)
PWA: назва, іконки, кольори	packages/frontend/public/manifest.json, public/icons/, public/splash/, public/favicon.svg
Логотип на сторінці входу	packages/frontend/src/views/Login.vue ('VIBE'), src/assets/logo.svg
Назва в PWA-кнопці встановлення	packages/frontend/src/components/MenuButton.vue
Тексти головної сторінки	packages/frontend/src/locales/*.ts (heroTitle, mobileTitle та ін.)
Кеш service worker	packages/frontend/src/service-worker.ts (__vibe_template_sw_error_queue__)
Листи (скидання пароля, підтвердження email)	packages/backend/src/app/services/auth/password-reset-service.ts, email-verification-service.ts
Промпти AI-підтримки	packages/backend/src/config/support.ts; у базу їх кладе db:seed
Назва БД за замовчуванням	packages/backend/src/config/database.ts (vibe_template)
robots.txt	packages/frontend/public/robots.txt

У .env змініть:

Змінна	Значення в .env.example	Навіщо
APP_NAME	uwebsockets-api	Назва застосунку в логах і конфігурації
REDIS_PREFIX	uwebsocket:	Префікс ключів Redis; різні проєкти на одному Redis не змішаються
PGSQL_DB_NAME	vibe_template	Своя база даних
SMTP_FROM_NAME, SMTP_FROM_EMAIL	—	Від кого приходять листи
VAPID_SUBJECT	mailto:example@gmail.com	Контакт для push-сервісів браузерів

Промпти AI кешуються в базі: якщо ви вже запускали db:seed, змініть їх в адмінці або перезапустіть seed на чистій базі.

Юридичні сторінки

PrivacyPolicy.vue, TermsAndConditions.vue, CookiesPolicy.vue і AiPolicy.vue у packages/frontend/src/views/ містять тексти шаблону. Перед публікацією замініть їх своїми, узгодженими з юристом.

2. Змінити інтерфейс

Що змінити	Де
Кольори, базові стилі	packages/frontend/src/assets/base.css, main.css (CSS-змінні --color-*)
Сторінки	packages/frontend/src/views/
Маршрути фронтенду і доступ	packages/frontend/src/router/index.ts (guard для залогінених і адмінів)
Шапка, меню, модалки входу	packages/frontend/src/components/ (AppHeader, MenuButton, AuthModals)
Тексти й мови	packages/frontend/src/locales/ (en, uk, pl; нову мову додають файлом і кодом у SHIPPED_LOCALE_CODES)

Деталі — на сторінці Фронтенд.

3. Додати свій домен

Шаблон не нав'язує предметну область: «нотатки» в туторіалі — лише приклад. Для власного ресурсу:

1. Бекенд. Пройдіть кроки з Як додати фічу: схеми в shared → таблиця й міграція → repository → transformer → service → controller → маршрут.
2. Фронтенд. Додайте сторінку в src/views/, маршрут у src/router/index.ts і метод у src/utils/api.ts. Типи запитів і відповідей імпортуйте зі shared/schemas і shared/responses, тоді зміна контракту на бекенді підсвітить фронтенд при pnpm typecheck (див. приклад).
3. Real-time, якщо потрібно. Подія з сервера — WebSocket: надіслати подію.

4. Обрати інтеграції

Кожна інтеграція вмикається змінними оточення. Без них сервер стартує, а відповідна функція повертає помилку. Що саме відбувається без кожного сервісу, показано в таблиці Що потрібно зараз, а що пізніше.

Є три рівні рішення:

Рішення	Що робити	Коли
Налаштувати	Заповнити змінні в .env за Конфігурацією	Функція потрібна
Залишити вимкненою	Нічого не робити. Сховати кнопки в інтерфейсі (наприклад, соцвхід у AuthModals.vue, пункт «Support» у меню)	Можливо, знадобиться пізніше
Видалити з коду	Прибрати маршрути, контролери, сервіси, сторінки і тести функції (див. нижче)	Точно не потрібна, і ви хочете менше коду підтримувати

Як видаляти функцію

Видаляйте від зовнішніх шарів до внутрішніх, щоб TypeScript підказував, що ще залежить від видаленого:

1. Сторінки й пункти меню у фронтенді, маршрути в src/router/index.ts.
2. Групу маршрутів у packages/backend/src/app/routes/http-routes.ts (і ws-routes.ts, якщо є WS-маршрути). Наприклад, AI-підтримка — це групи з prefix: 'support' і prefix: 'prompts', адмінські маршрути бази знань і WS-маршрути support_open_chat, support_chat.
3. Контролери, сервіси, репозиторії і transformers функції, разом з їхніми *.spec.ts.
4. Таблиці: приберіть їх зі schema.ts і згенеруйте міграцію (db:generate). Розширення pgvector потрібне, доки в схемі є колонка vector.
5. Змінні з .env.example і перевірки з validate-runtime-config.ts.

Після кожного кроку запускайте:

pnpm typecheck && pnpm lint && pnpm test

pnpm typecheck покаже імпорти видалених модулів, а layering.spec.ts у pnpm test перевірить, що шари не почали звертатися одне до одного в обхід правил.

Тільки API, без фронтенду

Якщо вам потрібен лише бекенд (мобільний застосунок, інтеграції), пакет frontend можна прибрати, а для ручної перевірки API використовувати API Playground. Детальніше у Вступі.

5. Перед першим деплоєм

• Пройдіть чекліст для production: зокрема CSRF_ALLOWED_ORIGINS (без нього production-сервер не стартує) і сильний APP_KEY.
• DOMAIN — ваш домен (без порту, якщо це 443), тоді wsUrl буде wss://<домен>/api/websocket.
• Інструкції зі збірки й запуску: Деплой.

Наступний крок

Деплой: збірка, Docker-образ, healthcheck і робота за проксі.