Кастомизация и деплой админ-панели 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 (например, ru). Убедитесь, что ключ совпадает с маркером в шаблоне. Это позволяет поддерживать мультиязычность админ-панели без дублирования компонентов.

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

Версии @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. Свяжитесь с нами для обсуждения вашего магазина.