Розробка кастомних плагінів Vendure: від ідеї до продакшену

Уявіть: ви налаштували 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; } } 

Чому кастомний плагін кращий за модифікацію ядра?

Етапи розробки: від концепції до запуску

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

• Вихідний код плагіна з коментарями українською
• Повна документація: встановлення, налаштування, інтеграція
• Інструкція з міграції бази даних
• Тестове покриття (unit + e2e) з використанням createTestEnvironment
• Підтримка протягом 2 тижнів після здачі (фікс багів, консультації)

Терміни та вартість

Терміни розробки кастомного плагіна: від 2 тижнів (прості розширення) до 6 тижнів (складні інтеграції). Вартість розраховується індивідуально після аналізу вимог. Ми пропонуємо фіксовану ціну та прозорі етапи оплати.

Довіряйте досвіду

Ми — команда сертифікованих розробників Vendure з 5-річним досвідом. За плечима більше 40 успішно запущених плагінів. Гарантуємо стабільність та своєчасну підтримку. Офіційна документація Vendure підтверджує, що плагіни — єдиний правильний спосіб розширення. Фреймворк NestJS забезпечує модульність і тестованість.

Зв'яжіться з нами, щоб обговорити ваш проєкт. Отримайте консультацію з розробки плагіна Vendure.