Building a CMS Integration Plugin

A CMS integration plugin allows you to automatically synchronize your Vendure product catalog with an external Content Management System.

This is done in a way that establishes Vendure as the source of truth for the ecommerce's data.

This guide demonstrates how to build a production-ready CMS integration plugin. The principles covered here are designed to be CMS-agnostic, however we do have working examples for various platforms.

Platfroms covered in the guide:

Working Example Repository

Info

This guide provides a high-level overview of building a CMS integration plugin. For complete implementations, refer to working examples repository

The code examples in this guide are simplified for educational purposes. The actual implementations contain additional features like error handling, retry logic, and performance optimizations.

Prerequisites

Node.js 20+ with npm package manager
An existing Vendure project created with the Vendure create command
An access key to a CMS platform that provides an API

Core Concepts

This plugin leverages several key Vendure concepts:

EventBus: Provides real-time notifications when entities are created, updated, or deleted.
Job Queues: Ensures that synchronization tasks are performed reliably and asynchronously, with retries on failure.
Plugin API: The foundation for extending Vendure with custom capabilities.

How It Works

The CMS integration follows a simple event-driven flow:

This ensures reliable, asynchronous synchronization with built-in retry capabilities.

Plugin Structure and Types

First, let's use the Vendure CLI to scaffold the basic plugin structure:

npx vendure add -p CmsPlugin

This command will create the basic plugin structure. Next, we'll generate the required services:

# Generate the main sync servicenpx vendure add -s CmsSyncService --selected-plugin CmsPlugin# Generate the CMS-specific service (replace with your CMS)npx vendure add -s CmsSpecificService --selected-plugin CmsPlugin# Explained later in the Event-Driven Synchronization Section

Now we start by defining the main plugin class, its services, and the configuration types.

Plugin Definition

The CmsPlugin class registers the necessary services (CmsSyncService, CmsSpecificService) and sets up any Admin API extensions.

src/plugins/cms/cms.plugin.ts

import { VendurePlugin, PluginCommonModule, Type, OnModuleInit } from '@vendure/core';import { CmsSyncService } from './services/cms-sync.service';import { CmsSpecificService } from './services/cms-specific.service';import { PluginInitOptions, CMS_PLUGIN_OPTIONS } from './types';// ...@VendurePlugin({    imports: [PluginCommonModule],    providers: [        { provide: CMS_PLUGIN_OPTIONS, useFactory: () => CmsPlugin.options },        CmsSyncService,        CmsSpecificService, // The service for the specific CMS platform    ],    // ...})export class CmsPlugin {    static options: PluginInitOptions;    static init(options: PluginInitOptions): Type<CmsPlugin> {        this.options = options;        return CmsPlugin;    }}

Configuration Types

The plugin's configuration options are defined in a types.ts file.

Create this file in your plugin directory to define the interfaces. These options will be passed to the plugin from your vendure-config.ts.

Note

This would be created for you automatically when you run the CLI command npx vendure add

src/plugins/cms/types.ts

import { ID, InjectionToken } from '@vendure/core';export interface PluginInitOptions {    cmsApiKey?: string;    CmsSpecificOptions?: any;    retryAttempts?: number;    retryDelay?: number;}export interface SyncJobData {    entityType: 'Product' | 'ProductVariant' | 'Collection';    entityId: ID;    operationType: 'create' | 'update' | 'delete';    timestamp: string;    retryCount: number;}export interface SyncResponse {    success: boolean;    message?: string;    error?: string;}

Event-Driven Synchronization

The plugin uses Vendure's EventBus to capture changes in real-time.

In the onModuleInit lifecycle hook, we create job queues and subscribe to entity events.

Creating Job Queues and Subscribing to Events

You can also scaffold job queue handlers using the CLI:

npx vendure add -j CmsProductSync --name productSyncQueue --selected-service CmsSyncService

This creates a productSyncQueue in the CmsSyncService. The service will be responsible for setting up the queues and processing the jobs. It will expose public methods to trigger new jobs.

src/plugins/cms/services/cms-sync.service.ts

import { Injectable, OnModuleInit } from '@nestjs/common';import { JobQueue, JobQueueService /* ... other imports */ } from '@vendure/core';import { SyncJobData } from '../types';@Injectable()export class CmsSyncService implements OnModuleInit {    private productSyncQueue: JobQueue<SyncJobData>;    private variantSyncQueue: JobQueue<SyncJobData>;    private collectionSyncQueue: JobQueue<SyncJobData>;    constructor(        private jobQueueService: JobQueueService,        // ... other dependencies    ) {}    async onModuleInit() {        this.productSyncQueue = await this.jobQueueService.createQueue({            name: 'cms-product-sync',            process: async job => {                return this.syncProductToCms(job.data);            },        });        this.variantSyncQueue = await this.jobQueueService.createQueue({            name: 'cms-variant-sync',            process: async job => {                return this.syncVariantToCms(job.data);            },        });        this.collectionSyncQueue = await this.jobQueueService.createQueue({            name: 'cms-collection-sync',            process: async job => {                return this.syncCollectionToCms(job.data);            },        });    }    triggerProductSync(data: SyncJobData) {        return this.productSyncQueue.add(data);    }    triggerVariantSync(data: SyncJobData) {        return this.variantSyncQueue.add(data);    }    triggerCollectionSync(data: SyncJobData) {        return this.collectionSyncQueue.add(data);    }    // ... other methods for the actual sync logic (e.g. syncProductToCms)}

Next, in the CmsPlugin, we subscribe to the EventBus and call the new service method to add a job to the queue whenever a relevant event occurs.

src/plugins/cms/cms.plugin.ts

import { OnModuleInit, EventBus, ProductEvent, VendurePlugin } from '@vendure/core';import { CmsSyncService } from './services/cms-sync.service';@VendurePlugin({    // ...    providers: [CmsSyncService /* ... */],})export class CmsPlugin implements OnModuleInit {    constructor(        private eventBus: EventBus,        private cmsSyncService: CmsSyncService,    ) {}    async onModuleInit() {        // Listen for Product events        this.eventBus.ofType(ProductEvent).subscribe(event => {            const syncData = this.extractSyncData(event);            this.cmsSyncService.triggerProductSync(syncData);        });        // Similar listeners for ProductVariantEvent and CollectionEvent...    }    // ...}

Implementing the Sync Logic

The sync logic is split into two services: a generic service to fetch data, and a specific service to communicate with the CMS.

CmsSyncService orchestrates the synchronization logic. It acts as the bridge between Vendure's internal systems and your CMS platform, handling data fetching, relationship resolution, and error management.

Tip

Separating orchestration logic from CMS-specific API calls allows for better testability and maintainability. The sync service handles Vendure-specific operations while CMS services focus on API communication.

Core Responsibilities

The sync service handles several critical functions:

Entity Data Fetching: Retrieves complete entity data with necessary relations
Translation Management: Handles Vendure's multi-language support
Relationship Resolution: Manages complex entity relationships
Error Handling: Provides consistent error handling and logging

Service Structure and Dependencies

The service follows Vendure's dependency injection pattern and requires several core Vendure services:

src/plugins/cms/services/cms-sync.service.ts

@Injectable()export class CmsSyncService implements OnApplicationBootstrap {    constructor(        @Inject(CMS_PLUGIN_OPTIONS) private options: PluginInitOptions,        private readonly connection: TransactionalConnection,        private readonly channelService: ChannelService,        private readonly collectionService: CollectionService,        private readonly requestContextService: RequestContextService,        // Your CMS-specific service        private readonly CmsSpecificService: CmsSpecificService,        private processContext: ProcessContext,    ) {}    async onApplicationBootstrap() {        // Ensure this logic only runs on the Vendure worker, and not the server        if (this.processContext.isWorker) {            // This is where you would add any necessary setup or initialization logic            // for example, ensuring that the CMS has compatible content types.        }    }}

Product Synchronization

Product sync demonstrates the complete workflow from job processing to CMS communication:

async syncProductToCms(jobData: SyncJobData): Promise<SyncResponse> {  try {    // Fetch fresh product data from database with translations    const product = await this.connection.rawConnection      .getRepository(Product)      .findOne({        where: { id: jobData.entityId },        relations: { translations: true },      });    if (!product) {      throw new Error(`Product with ID ${jobData.entityId} not found`);    }    const operationType = jobData.operationType;    const defaultLanguageCode = await this.getDefaultLanguageCode();    // Get product slug using translation utilities    const productSlug = this.translationUtils.getSlugByLanguage(      product.translations,      defaultLanguageCode,    );    // Delegate to CMS-specific service    await this.CmsSpecificService.syncProduct({      product,      defaultLanguageCode,      operationType,      productSlug,    });    return {      success: true,      message: `Product ${jobData.operationType} synced successfully`,      timestamp: new Date(),    };  } catch (error) {    const errorMessage = error instanceof Error ? error.message : 'Unknown error';    Logger.error(`Product sync failed: ${errorMessage}`, error.stack);    return {      success: false,      message: `Product sync failed: ${errorMessage}`,    };  }}

Relationship Handling

The service includes methods to resolve entity relationships. For example, finding collections that contain a specific variant:

async findCollectionsForVariant(  variantId: string | number,): Promise<Collection[]> {  try {    const variant = await this.connection.rawConnection      .getRepository(ProductVariant)      .findOne({        where: {          id: variantId,        },        relations: ["collections"],      });    return variant?.collections || [];  } catch (error) {    Logger.error(      `Failed to find collections for variant ${variantId}`,      String(error),    );    return [];  }}    return collectionsWithVariant;  } catch (error) {    // Variants can have no collecitons, therefore, sync anyways.    Logger.error(`Failed to find collections for variant ${variantId}`, String(error));    return [];  }}

Additional Entity Types

The service can also includes syncVariantToCms() and syncCollectionToCms() methods that follow the same pattern as the product sync shown above.

These implementations are omitted from this guide for brevity, but they handle their respective entity types with similar data fetching, relationship resolution, and error handling patterns.

The complete implementations can be found in the working example repositories.

This sync service provides the foundation for handling all Vendure-specific complexity while delegating CMS API communication to specialized services.

Platform specific setup

Working Example

The complete, production-ready Storyblok implementation can be found in the Storyblok integration example. Refer to it for a minimal working implementation.

Setting up Storyblok Space

1. Create a Storyblok Account and Space

Sign up at storyblok.com if you don't have an account
Create a new Space (equivalent to a project in Storyblok)
Choose a suitable plan based on your needs

2. Get Your API Credentials

Navigate to Settings → Access Tokens in your Storyblok space
Create a new Management API Token with write permissions
Note down your Space ID (found in Settings → General)

3. Configure Environment Variables

Add these variables to your .env file:

Env

STORYBLOK_API_KEY=your_management_api_tokenSTORYBLOK_SPACE_ID=your_space_id

The Storyblok Service

StoryblokService handles all Storyblok-specific operations including API communication, content type management, and data transformation. Key features include:

Content Type Management: Automatically creates Vendure-specific content types (components) in Storyblok
Story Management: CRUD operations for stories representing products, variants, and collections
Relationship Handling: Manages references between products, variants, and collections

Basic Service Structure

The service follows Vendure's standard dependency injection pattern and implements OnApplicationBootstrap to ensure Storyblok is properly configured before handling sync operations.

src/plugins/cms/services/storyblok.service.ts

// Define component types as constants for consistency and maintainabilityconst COMPONENT_TYPE = {    product: 'vendure_product',    product_variant: 'vendure_product_variant',    collection: 'vendure_collection',};@Injectable()export class StoryblokService implements OnApplicationBootstrap {    constructor(@Inject(CMS_PLUGIN_OPTIONS) private options: PluginInitOptions) {}    async onApplicationBootstrap() {        // This is where you would add any necessary setup or initialization logic        // for example, ensuring that the CMS has compatible content types.    }    // Main entry point for product synchronization    // The operationType determines which CRUD operation to perform    async syncProduct({ product, defaultLanguageCode, operationType }) {        switch (operationType) {            case 'create':                return this.createStoryFromProduct(product, defaultLanguageCode);            case 'update':                return this.updateStoryFromProduct(product, defaultLanguageCode);            case 'delete':                return this.deleteStoryFromProduct(product, defaultLanguageCode);        }    }}

Making API Requests

All Storyblok API communication is centralized through a single method that handles authentication, error handling, and response parsing. This approach ensures consistent behavior across all operations.

private async makeStoryblokRequest({ method, endpoint, data }) {    // Construct the full API URL using the configured space ID    const url = `https://mapi.storyblok.com/v1/spaces/${this.options.storyblokSpaceId}/${endpoint}`;    const response = await fetch(url, {        method,        headers: {            Authorization: this.options.storyblokApiKey,            'Content-Type': 'application/json',        },        // Only include request body for POST/PUT operations        body: data ? JSON.stringify(data) : undefined,    });    if (!response.ok) {        // Provide clear error messages for debugging API issues        throw new Error(`Storyblok API error: ${response.status}`);    }    return response.json();}

Data Transformation

Transformation methods convert Vendure entities into the format expected by Storyblok's API. The content object structure must match the component schema defined in Storyblok.

private async transformProductData(product, defaultLanguageCode, productSlug?) {    // Extract the translation for the default language    // Vendure stores translations in an array, so we need to find the correct one    const translation = product.translations.find(        t => t.languageCode === defaultLanguageCode    );    if (!translation) {        return undefined; // Skip if no translation exists    }    // Find all variant story UUIDs for this product using relationship handling    const variantStoryIds = await this.findVariantStoriesForProductUuids(        product.id,        defaultLanguageCode,        productSlug,    );    return {        story: {            name: translation?.name, // Story name in Storyblok            slug: translation?.slug,  // URL slug for the story            content: {                component: COMPONENT_TYPE.product, // Must match the component name in Storyblok                vendureId: product.id.toString(),  // Store Vendure ID for reference                variants: variantStoryIds, // Array of story UUIDs for product variants            },        },        publish: 1, // Auto-publish the story (1 = published, 0 = draft)    };}

Relationship Handling

One of the most important aspects of CMS integration is maintaining relationships between entities. Products have variants, variants belong to collections, and these relationships need to be reflected in the CMS. Storyblok uses story UUIDs to create references between content pieces.

Finding Related Entities

First, we need methods to query the Vendure database for related entities:

// Find all product variants for a given product ID from the databaseprivate async findProductVariants(productId: string | number): Promise<ProductVariant[]> {    try {        return await this.connection.rawConnection            .getRepository(ProductVariant)            .find({                where: { productId: productId as any },                relations: ['translations'], // Include translations for slug generation                order: { id: 'ASC' },            });    } catch (error) {        Logger.error(`Failed to find variants for product ${productId}`, String(error));        return [];    }}

Batch Story Lookups

We can also use batch lookups to find multiple stories at once:

// Batch lookup method for efficient story retrievalprivate async findStoriesBySlugs(slugs: string[]): Promise<Map<string, any>> {    const storyMap = new Map<string, any>();    if (slugs.length === 0) return storyMap;    try {        // Storyblok supports comma-separated slugs for batch lookup        const slugsParam = slugs.join(',');        const response = await this.makeStoryblokRequest({            method: 'GET',            endpoint: `stories?by_slugs=${slugsParam}`,        });        if (response.stories) {            for (const story of response.stories) {                storyMap.set(story.slug, story);            }        }    } catch (error) {        Logger.error(`Failed to find stories by slugs: ${slugs.join(', ')}`, String(error));    }    return storyMap;}

Building Relationships

Finally, we combine database queries with CMS lookups to build relationships:

// Find variant stories using batch lookup for efficiencyprivate async findVariantStoriesForProductUuids(    productId: string | number,    defaultLanguageCode: LanguageCode,    productSlug?: string | null,): Promise<string[]> {    if (!productSlug) return [];    // Get all variants for this product from Vendure database    const variants = await this.findProductVariants(productId);    // Generate slugs for all variants (convention: product-slug-variant-id)    const variantSlugs = variants.map(        (variant) => `${productSlug}-variant-${variant.id}`,    );    if (variantSlugs.length === 0) return [];    // Batch lookup all variant stories and extract UUIDs    const storiesMap = await this.findStoriesBySlugs(variantSlugs);    const storyUuids: string[] = [];    for (const [slug, story] of storiesMap) {        if (story?.uuid) {            storyUuids.push(story.uuid.toString()); // Storyblok uses UUIDs for references        }    }    return storyUuids;}// Example: Transform variant data with relationshipsprivate async transformVariantData(    variant: ProductVariant,    defaultLanguageCode: LanguageCode,    variantSlug: string,    collections?: Collection[],) {    const translation = variant.translations.find(        t => t.languageCode === defaultLanguageCode    );    if (!translation) return undefined;    // Find parent product and collection references using the same batch lookup patterns    const parentProductStoryUuid = await this.findParentProductStoryUuid(variant, defaultLanguageCode);    const collectionStoryUuids = await this.findCollectionStoryUuids(collections, defaultLanguageCode);    return {        story: {            name: translation.name,            slug: variantSlug,            content: {                component: COMPONENT_TYPE.product_variant,                vendureId: variant.id.toString(),                parentProduct: parentProductStoryUuid ? [parentProductStoryUuid] : [],                collections: collectionStoryUuids,            },        },        publish: 1,    };}// Additional relationship methods like findParentProductStoryUuid and findCollectionStoryUuids// follow similar patterns and are available in the working example repository.

CRUD Operations

These methods handle the basic Create, Read, Update, and Delete operations for stories in Storyblok. They follow REST API conventions and leverage the centralized request method for consistent behavior.

// Create a new story in Storyblokprivate async createStoryFromProduct(product, defaultLanguageCode) {    // Transform Vendure product data into Storyblok story format    const data = this.transformProductData(product, defaultLanguageCode);    // POST to the stories endpoint to create a new story    return this.makeStoryblokRequest({        method: 'POST',        endpoint: 'stories',        data,    });}// Find an existing story by its slugprivate async findStoryBySlug(slug: string) {    // Use Storyblok's by_slugs query parameter for efficient lookup    const response = await this.makeStoryblokRequest({        method: 'GET',        endpoint: `stories?by_slugs=${slug}`,    });    // Return the matching story or undefined if not found    return response.stories.find((story: any) => story.slug === slug);}// Additional CRUD methods like updateStoryFromProduct and deleteStoryFromProduct// follow similar patterns with PUT and DELETE HTTP methods respectively.// Full implementations are available in the working example repository.

Final Plugin Configuration

src/vendure-config.ts

CmsPlugin.init({  cmsApiKey: process.env.STORYBLOK_API_KEY,  storyblokSpaceId: process.env.STORYBLOK_SPACE_ID,}),

This setup provides a complete Storyblok CMS integration that automatically creates the necessary content types and syncs your Vendure catalog with structured content in Storyblok.

The complete implementations can be found in the working example repositories.

Admin API Integration

To allow for manual synchronization through graphQL mutations, we can extend the Admin API with new mutations. Let's use the CLI to generate the API extensions:

# Generate API extensions for the CMS pluginnpx vendure add -a CmsSyncAdminResolver --selected-plugin CmsPlugin

Extending the GraphQL API

src/plugins/cms/api/api-extensions.ts

export const adminApiExtensions = gql`  extend type Mutation {    syncProductToCms(productId: ID!): SyncResponse!    syncCollectionToCms(collectionId: ID!): SyncResponse!  }  // ...`;

Implementing the Resolver

The resolver for these mutations re-uses the existing CmsSyncService to add a job to the queue.

src/plugins/cms/api/cms-sync-admin.resolver.ts

@Resolver()export class CmsSyncAdminResolver {    constructor(private cmsSyncService: CmsSyncService) {}    @Mutation()    @Allow(Permission.UpdateCatalog)    async syncProductToCms(@Args() args: { productId: ID }): Promise<SyncResponse> {        // This creates the data payload for the job        const syncData: SyncJobData = {            entityType: 'Product',            entityId: args.productId,            operationType: 'update', // Manual syncs are usually 'update'            timestamp: new Date().toISOString(),            retryCount: 0,        };        // The service method adds the job to the queue        await this.cmsSyncService.triggerProductSync(syncData);        return {            success: true,            message: `Successfully queued sync for product ${args.productId}.`,        };    }    // ... resolver for collection sync}

Final Configuration

Finally, add the plugin to your vendure-config.ts file with the appropriate configuration for your chosen CMS platform.

src/vendure-config.ts

import { VendureConfig } from '@vendure/core';import { CmsPlugin } from './plugins/cms/cms.plugin';export const config: VendureConfig = {    // ... other config    plugins: [        // ... other plugins        CmsPlugin.init({            // Configure based on your chosen CMS platform            // See platform-specific tabs above for exact configuration            cmsApiKey: process.env.CMS_API_KEY,            // Additional CMS-specific options...        }),    ],};

Refer to the platform-specific configuration examples in the tabs above for the exact environment variables and options needed for your chosen CMS.

For complete, production-ready implementations, see the working examples: