Разработка кастомных плагинов 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.