Представьте: вы настроили Vendure, но требуется программа лояльности. Стандартных средств нет, документация скупа, а готовые решения не гибкие. Разработка кастомного плагина — единственный путь, но он полон подводных камней: неправильная обработка событий разрушает целостность данных, ошибки в GraphQL-схеме ломают фронтенд. Мы прошли через это 40+ раз. Согласно официальной документации Vendure, плагины — единственный способ расширения без модификации ядра.
Мы разрабатываем кастомные плагины Vendure под ключ: от аналитики до деплоя. Типичный запрос клиента — программа лояльности с баллами, но документации Vendure недостаточно, а готовые решения не подходят. Мы берем на себя полный цикл: анализируем требования, проектируем архитектуру, пишем код, покрываем тестами и деплоим. В результате вы получаете стабильный плагин, который работает под нагрузкой и не ломается при обновлении Vendure. За 5 лет мы реализовали более 40 плагинов для Vendure — от простых расширений до сложных интеграций с ERP.
Проблемы, которые решаем
- Расширение GraphQL-схемы: добавляем поля в существующие типы (например,
loyaltyAccountвCustomer), не ломая обратную совместимость. Используемextend typeи резолверы сResolveField. Это сокращает время интеграции на 30%. - Асинхронная обработка событий: начисление баллов после завершения заказа, отправка уведомлений. Подписываемся на
OrderPlacedEventчерез EventBus. - Интеграция с внешними системами: CRM, ERP, платежные шлюзы. Плагин может содержать HTTP-клиенты и очереди сообщений. Например, при разработке плагина программы лояльности мы сократили время на интеграцию с CRM на 40%.
- Тестирование: используем
createTestEnvironmentот Vendure для изолированного тестирования без моков. Тесты запускаются на in-memory SQLite. Покрытие достигает 95%.
Как создать кастомный плагин Vendure для программы лояльности?
Одна из ключевых проблем — правильная обработка событий. В Vendure стандартный EventBus работает на NestJS EventEmitter, но нужно учитывать транзакционность. Мы используем TransactionalConnection для гарантии согласованности данных. Также важно не допустить N+1 запросов при расширении GraphQL-схемы — DataLoader с batch-запросами решает эту проблему.
Как тестировать кастомный плагин Vendure?
Для тестирования плагина используем createTestEnvironment от Vendure. Он поднимает полный инстанс Vendure с in-memory SQLite, что позволяет запускать unit и e2e-тесты без внешних зависимостей. Тестовое покрытие достигает 95%, включая проверку обработки событий и GraphQL-запросов.
Структура плагина Vendure
Каждый плагин — это NestJS модуль с декоратором @VendurePlugin. Рекомендуемая структура:
src/plugins/loyalty/
├── loyalty.plugin.ts # Точка входа (NestJS Module)
├── loyalty.service.ts # Бизнес-логика
├── loyalty.resolver.ts # GraphQL резолверы
├── loyalty.entity.ts # TypeORM сущность
├── loyalty-ui/ # Admin UI расширение (опционально)
│ ├── loyalty.module.ts
│ └── components/
└── types.ts # GraphQL типы
Декоратор @VendurePlugin
// loyalty.plugin.ts
import { PluginCommonModule, Type, VendurePlugin } from "@vendure/core";
import { LoyaltyService } from "./loyalty.service";
import { LoyaltyResolver } from "./loyalty.resolver";
import { LoyaltyAccount } from "./loyalty.entity";
import { loyaltyShopApiExtensions, loyaltyAdminApiExtensions } from "./api-extensions";
@VendurePlugin({
imports: [PluginCommonModule],
entities: [LoyaltyAccount],
shopApiExtensions: {
schema: loyaltyShopApiExtensions,
resolvers: [LoyaltyResolver],
},
adminApiExtensions: {
schema: loyaltyAdminApiExtensions,
resolvers: [LoyaltyAdminResolver],
},
providers: [LoyaltyService],
configuration: (config) => {
config.orderOptions.orderItemPriceCalculationStrategy =
new LoyaltyAwarePriceStrategy();
return config;
},
})
export class LoyaltyPlugin {}
TypeORM сущность
// loyalty.entity.ts
import {
DeepPartial,
Entity,
Column,
PrimaryGeneratedColumn,
ManyToOne,
CreateDateColumn,
UpdateDateColumn,
} from "typeorm";
import { Customer, VendureEntity } from "@vendure/core";
@Entity()
export class LoyaltyAccount extends VendureEntity {
constructor(input?: DeepPartial<LoyaltyAccount>) {
super(input);
}
@ManyToOne(() => Customer, { onDelete: "CASCADE" })
customer: Customer;
@Column()
customerId: string;
@Column({ default: 0 })
points: number;
@Column({ type: "jsonb", nullable: true })
transactions: LoyaltyTransaction[];
@CreateDateColumn()
createdAt: Date;
@UpdateDateColumn()
updatedAt: Date;
}
interface LoyaltyTransaction {
type: "earn" | "spend";
points: number;
orderId?: string;
reason: string;
date: string;
}
Сервис с EventBus
// loyalty.service.ts
import { Injectable } from "@nestjs/common";
import { EventBus, OrderPlacedEvent, RequestContext, TransactionalConnection } from "@vendure/core";
import { OnEvent } from "@nestjs/event-emitter";
import { LoyaltyAccount } from "./loyalty.entity";
@Injectable()
export class LoyaltyService implements OnApplicationBootstrap {
constructor(
private connection: TransactionalConnection,
private eventBus: EventBus,
) {}
onApplicationBootstrap() {
this.eventBus.ofType(OrderPlacedEvent).subscribe(async (event) => {
await this.awardPointsForOrder(event.ctx, event.order);
});
}
async awardPointsForOrder(ctx: RequestContext, order: Order) {
const customerId = order.customerId;
if (!customerId) return;
const pointsToAward = Math.floor(order.totalWithTax / 100);
await this.connection.withTransaction(ctx, async (em) => {
let account = await em.findOne(LoyaltyAccount, {
where: { customerId },
});
if (!account) {
account = new LoyaltyAccount({
customerId,
points: 0,
transactions: [],
});
}
account.points += pointsToAward;
account.transactions = [
...account.transactions,
{
type: "earn",
points: pointsToAward,
orderId: order.id,
reason: `Заказ #${order.code}`,
date: new Date().toISOString(),
},
];
await em.save(account);
});
}
async getAccountByCustomer(ctx: RequestContext, customerId: string) {
return this.connection
.getRepository(ctx, LoyaltyAccount)
.findOne({ where: { customerId } });
}
async redeemPoints(ctx: RequestContext, customerId: string, points: number) {
const account = await this.getAccountByCustomer(ctx, customerId);
if (!account || account.points < points) {
throw new UserInputError("Недостаточно баллов");
}
account.points -= points;
account.transactions.push({
type: "spend",
points,
reason: "Списание при заказе",
date: new Date().toISOString(),
});
return this.connection.getRepository(ctx, LoyaltyAccount).save(account);
}
}
GraphQL Resolver
// loyalty.resolver.ts
import { Resolver, Query, Mutation, Args, ResolveField, Parent } from "@nestjs/graphql";
import { Ctx, RequestContext, Allow, Permission, ActiveOrderService } from "@vendure/core";
import { LoyaltyService } from "./loyalty.service";
@Resolver()
export class LoyaltyResolver {
constructor(
private loyaltyService: LoyaltyService,
private activeOrderService: ActiveOrderService,
) {}
@Query()
@Allow(Permission.Owner)
async myLoyaltyAccount(@Ctx() ctx: RequestContext) {
if (!ctx.activeUserId) return null;
return this.loyaltyService.getAccountByCustomer(
ctx,
ctx.activeUserId.toString()
);
}
@Mutation()
@Allow(Permission.Owner)
async redeemLoyaltyPoints(
@Ctx() ctx: RequestContext,
@Args("points") points: number,
) {
const order = await this.activeOrderService.getActiveOrder(ctx, undefined);
if (!order) throw new Error("No active order");
await this.loyaltyService.redeemPoints(ctx, ctx.activeUserId!.toString(), points);
return order;
}
}
Почему кастомный плагин лучше модификации ядра?
| Критерий | Кастомный плагин | Модификация ядра |
|---|---|---|
| Обновление Vendure | Обновляется независимо | Требует слияния изменений |
| Повторное использование | Легко портируется на другие проекты | Привязан к проекту |
| Тестирование | Изолированные тесты | Требует полной настройки окружения |
| Поддержка | Документированный API | Нет гарантий совместимости |
Этапы разработки: от концепции до запуска
| Этап | Длительность | Результат |
|---|---|---|
| Анализ требований | 2-3 дня | Техническое задание, прототип |
| Проектирование архитектуры | 1-2 дня | ER-диаграмма, GraphQL-схема |
| Реализация ядра | 5-7 дней | Готовый код с комментариями |
| Admin UI (опционально) | 2-3 дня | Расширение админки |
| Тестирование | 2-3 дня | Unit + e2e, отчет о покрытии |
| Документация и деплой | 1 день | Инструкция, миграции, выкладка |
Что входит в работу
- Исходный код плагина с комментариями на русском
- Полная документация: установка, настройка, интеграция
- Инструкция по миграции базы данных
- Тестовое покрытие (unit + e2e) с использованием
createTestEnvironment - Поддержка в течение 2 недель после сдачи (фикс багов, консультации)
Типичные ошибки при разработке
- Не подписываются на события в
onApplicationBootstrap— EventBus не срабатывает. - Используют прямой запрос к TypeORM вместо
TransactionalConnection— теряется целостность данных. - Не указывают сущности в
entities— таблицы не создаются. - Путают Shop API и Admin API при расширении схемы — резолверы не работают.
Сроки и стоимость
Сроки разработки кастомного плагина: от 2 недель (простые расширения) до 6 недель (сложные интеграции). Стоимость рассчитывается индивидуально после анализа требований. Мы предлагаем фиксированную цену и прозрачные этапы оплаты.
Доверять опыту
Мы — команда сертифицированных разработчиков Vendure с 5-летним опытом. За плечами более 40 успешно запущенных плагинов. Гарантируем стабильность и своевременную поддержку. Официальная документация Vendure подтверждает, что плагины — единственный правильный способ расширения. Фреймворк NestJS обеспечивает модульность и тестируемость.
Свяжитесь с нами, чтобы обсудить ваш проект. Получите консультацию по разработке плагина Vendure.