Building a CMS Integration Plugin for Vendure

Building a CMS Integration Plugin for Vendure | Vendure Docs

# 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

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;    }}

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;}

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)}

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...    }    // ...}

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.        }    }}

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}`,    };  }}

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 [];  }}

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.

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

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

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}

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...        }),    ],};

Building a CMS Integration Plugin

Working Example Repository

Prerequisites

Building a CMS Integration Plugin

Working Example Repository

Prerequisites

How It Works

Plugin Structure and Types

Plugin Definition

Configuration Types

Event-Driven Synchronization

Creating Job Queues and Subscribing to Events

Implementing the Sync Logic

Core Responsibilities

Service Structure and Dependencies

Product Synchronization

Relationship Handling

Platform specific setup

1. Create a Storyblok Account and Space

2. Get Your API Credentials

3. Configure Environment Variables

Admin API Integration

Extending the GraphQL API

Implementing the Resolver

Final Configuration

Core Concepts