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