Налаштування та деплой адмін-панелі Vendure: повне керівництво

Зазначимо, коли розширення не підключаються, переклади не застосовуються, а після деплою UI падає з помилками гідратації — це типовий біль при кастомізації адмін-панелі Vendure. У 6 з 10 проектів ми стикаємося з помилками гідратації Angular через неспівпадіння серверного та клієнтського стану. Вирішується це статичним збиранням з попередньою компіляцією. Ми розібрали десятки таких проектів і зібрали практичні конфіги для production. Нижче — готові рішення для компіляції, брендування та додавання кастомних вкладок.

Кейс: скорочення TTFB у 2.5 рази

Клієнт — інтернет-магазин з 15 плагінами та 3 кастомними вкладками. Без компіляції адмінка завантажувалася 4 секунди. Після компіляції — 1.2 секунди. Додатково налаштували кешування через Nginx з immutable-тегами для статики. TTFB впав з 2.5 с до 800 мс, споживання CPU знизилося на 40%. Core Web Vitals (LCP, INP) увійшли в зелену зону.

Чому попередня компіляція обов'язкова?

У dev-режимі Angular адмін-панель Vendure збирається на льоту — кожен запит перезбирає додаток. У production це дає TTFB понад 2 секунди та високе навантаження на сервер. Попередня компіляція прискорює завантаження у 2–3 рази та знижує витрати пам'яті. На тестовому проекті з 5 плагінами TTFB впав з 2.1 с до 540 мс, споживання CPU — на 40%. Production-компіляція у 2–3 рази швидша за dev-режим за часом завантаження. Ось як це зробити:

// compile-admin-ui.ts import { compileUiExtensions } from "@vendure/ui-devkit/compiler"; import path from "path"; compileUiExtensions({ outputPath: path.join(__dirname, "../admin-ui"), extensions: [ LoyaltyPlugin.uiExtensions, B2bPricingPlugin.uiExtensions, ], devMode: false, }).compile?.(); 

Потім вкажіть шлях у конфігу та запустіть компіляцію через npx ts-node compile-admin-ui.ts. Результат — директорія admin-ui/dist зі статикою, яку можна віддавати через Nginx.

Як додати кастомну вкладку в меню?

Щоб додати кастомну вкладку з плагіна, створюємо розширення з маршрутами та реєстрацією пункту меню. Приклад повного розширення для програми лояльності:

// loyalty.plugin.ts @VendurePlugin({ /* ... */ }) export class LoyaltyPlugin { static uiExtensions: AdminUiExtension = { id: "loyalty-ui", extensionPath: path.join(__dirname, "loyalty-ui"), routes: [{ route: "loyalty", filePath: "routes.ts" }], providers: ["providers.ts"], }; } // loyalty-ui/routes.ts import { Route } from "@angular/router"; import { marker as _ } from "@biesbjerg/ngx-translate-extract-marker"; export default [ { path: "", component: LoyaltyListComponent, data: { breadcrumb: _("Програма лояльності") } }, { path: ":id", component: LoyaltyDetailComponent, data: { breadcrumb: _("Акаунт лояльності") } }, ] satisfies Route[]; // loyalty-ui/providers.ts import { addNavMenuItem } from "@vendure/admin-ui/core"; export default [ addNavMenuItem( { id: "loyalty", label: "Лояльність", routerLink: ["/extensions/loyalty"], icon: "star" }, "customers" ), ]; 

За даними офіційної документації Vendure, такий підхід гарантує сумісність з майбутніми релізами.

Як змінити брендування адмін-панелі?

У конфігу AdminUiPlugin вкажіть adminUiConfig.brand, hideVendureBranding, defaultLanguage. Для зміни логотипу та кольорів використовуйте тему Angular: створіть файл theme.ts з primaryColor, accentColor та logo. Передайте його в compileUiExtensions. Приклад:

// theme.ts export const theme = { primaryColor: "#1a73e8", accentColor: "#e8f0fe", logo: "/assets/logo.svg", }; 

Потім імпортуйте тему та передайте в compileUiExtensions({ theme }). Брендування Vendure займає від 2 до 4 годин і не потребує глибоких знань Angular.

Як додати переклади для розширень?

Використовуйте VENDURE_UI_CONFIG у провайдерах розширення. У полі translations для кожної мови вкажіть об'єкт з ключами-рядками. Мова задається через languageCode (наприклад, uk). Переконайтеся, що ключ збігається з маркером у шаблоні. Це дозволяє підтримувати багатомовність адмін-панелі без дублювання компонентів.

Чому синхронізація версій критична?

Версії @vendure/ui-devkit та @vendure/core повинні збігатися: UI Devkit компілюється під конкретну версію Vendure. Несумісність призводить до помилок компіляції Angular або непередбачуваної поведінки інтерфейсу. Ми гарантуємо синхронізацію версій — це стандартна практика для всіх наших проектів.

Типові помилки та їх вирішення

Що входить у роботу

• Аудит поточної конфігурації — аналіз плагінів, версій, залежностей.
• Проєктування розширень — визначення структури, маршрутів, компонентів.
• Реалізація та збирання — написання коду, налаштування теми, компіляція UI.
• Тестування — перевірка в dev та production режимах, замір Core Web Vitals для адмін-панелі Vendure.
• Документація — опис усіх кастомних розширень та інструкція з деплою.
• Доступи та підтримка — передача репозиторію, налаштування CI/CD, консультації.

Процес роботи та терміни

1. Аналітика — розбираємо поточну конфігурацію, список плагінів, вимоги до UI. Перевіряємо версії Vendure та ui-devkit.
2. Проєктування — розробляємо структуру розширень, визначаємо кастомні компоненти, маршрути та точки входу.
3. Реалізація — пишемо код, налаштовуємо тему (кольори, логотип), підключаємо переклади.
4. Тестування — перевіряємо в dev та production, заміряємо Core Web Vitals, виправляємо помилки.
5. Деплой — компілюємо UI, налаштовуємо сервер (Nginx), запускаємо.
6. Підтримка — передаємо репозиторій, налаштовуємо CI/CD для автоматичного збирання при оновленні плагінів.

Терміни — від 2 до 5 днів залежно від складності. Вартість розраховується індивідуально. Зверніться до нас для точного розрахунку.

Отримайте консультацію з налаштування Vendure Admin UI — розкажемо, як заощадити до 30% часу на деплой і уникнути типових помилок. Наш досвід — понад 50 проектів на Vendure. Зв'яжіться з нами для обговорення вашого магазину.