Real-World Implementation: E-commerce Platform Plugins
Case study: Building and integrating plugins for an e-commerce platform.
Chapter 11: Real-World Implementation — E-commerce Platform Plugins
The previous chapters built the architecture from principles: manifests, lifecycles, registries, SDKs, events, security, testing. This chapter and the two that follow apply that architecture to concrete domains. Abstract plugin systems are easy to design; the interesting questions emerge when you have real business requirements, real compliance obligations, and real performance constraints.
E-commerce is a particularly demanding domain to start with. Payment processing sits at the intersection of security, compliance, and user experience in a way that few other plugin extension points do. Merchants need to customise their stores without writing code. Third-party services need to hook into the order lifecycle without touching the platform's core. Performance matters in a direct, measurable way — a slow checkout page costs money.
We will walk through a fictional platform called ShopSphere to illustrate how these requirements shape plugin architecture decisions, then examine how Vendure, a real production e-commerce platform built on NestJS and TypeScript, made different architectural choices for good reasons.
11.1 E-commerce Plugin Requirements
ShopSphere serves thousands of merchants globally. Its plugin system must accommodate payment gateways for different markets — Stripe, PayPal, Adyen, and regional banking integrations — each with different APIs, different error formats, and different compliance requirements. It needs shipping calculators that can query carrier APIs in real time, apply merchant-defined rules like free shipping thresholds, and handle the unavailability of carrier APIs gracefully. Marketing tools need to hook into the purchase flow at specific points without slowing down the checkout itself. Merchants want to add product customisation features — engraving, gift wrapping, personalised images — without asking a developer to modify the product page.
The architectural constraints that follow from these requirements are stringent. All plugins must follow the PluginManifest → PluginModule → PluginSDK contracts established in earlier chapters, because ShopSphere needs to enforce permission checks before executing any plugin code. Payment plugins cannot be trusted with the full DOM — they need to run in isolated contexts so that a compromised payment plugin cannot read form data from unrelated parts of the page. Plugins must load at runtime so merchants can add and remove them through an admin interface without a deployment. And the core checkout flow must remain fast even when ten plugins are active.
11.2 Case Study: Payment Plugin System
Payment processing is the most constrained extension point on the platform. A payment plugin has access to sensitive financial data, must meet PCI DSS compliance requirements, and runs at the moment where a broken experience costs the merchant a sale.
Architecture Design
The manifest for a payment plugin carries fields beyond the standard set, because the host application needs to know about currency support and compliance status before presenting the gateway as an option:
{
"id": "payments.stripe",
"name": "Stripe Payment Gateway",
"version": "1.2.0",
"entry": "/plugins/payments/stripe/index.js",
"permissions": ["api:payments", "ui:checkout"],
"icon": "/plugins/payments/stripe/logo.png",
"metadata": {
"supportedCurrencies": ["USD", "EUR", "GBP"],
"pciCompliant": true
}
}The metadata.supportedCurrencies field lets the host filter available payment options based on the merchant's location and the customer's currency. The pciCompliant flag is a declaration, not a guarantee — the host validates it against a signed certificate from an approved PCI DSS auditor before granting the api:payments permission.
SDK Integration
The plugin registers its checkout form as a route and subscribes to the checkout:submit event. The critical security property here is that payment data never passes through the host application — the Stripe SDK inside the plugin communicates directly with Stripe's servers:
export const module: PluginModule = {
mount(sdk) {
sdk.routes.add({
path: '/checkout/payment/stripe',
component: StripeCheckoutForm,
});
sdk.events.on('checkout:submit', async (order) => {
const paymentResult = await processStripePayment(order);
sdk.events.emit('payment:completed', paymentResult);
});
},
unmount(sdk) {
sdk.routes.remove('/checkout/payment/stripe');
sdk.events.off('checkout:submit', processStripePayment);
},
};The StripeCheckoutForm component uses Stripe Elements — an iframe-based UI component that Stripe serves and controls — to collect card details. The host application's DOM never sees the raw card number. From a PCI DSS perspective, this means ShopSphere is in scope for the lightest compliance tier (SAQ A), because cardholder data is handled entirely by the third-party processor.
The api:payments permission controls which SDK methods the plugin can call, but it also signals to the host that this plugin's checkout route should be rendered inside a shadow root with a restrictive Content Security Policy, preventing it from injecting scripts or reading cookies from the broader checkout page.
Multi-Gateway Coordination
When multiple payment plugins are installed, the platform needs to select the appropriate gateway based on the order context. This is handled through a service that aggregates all registered gateways and filters by currency, amount, and merchant configuration:
interface PaymentGatewayService {
registerGateway(id: string, gateway: PaymentGateway): void;
getAvailableGateways(context: PaymentContext): PaymentGateway[];
}
// Each payment plugin registers itself
sdk.services.register('payments', {
registerGateway: (id, gateway) => gatewayRegistry.set(id, gateway),
});
// ShopSphere checkout reads from the registry
const gateways = sdk.services.get<PaymentGatewayService>('payments');
const available = gateways.getAvailableGateways({ currency: order.currency, amount: order.total });This is the service registration pattern from chapter 7, applied to a real coordination problem. The checkout page does not know which payment plugins are installed — it queries the service and renders whatever is available for the current context.
11.3 Product Customisation Plugins
Merchants want to offer product personalisation — engraving, gift wrapping, custom imagery — without paying a developer to modify the product page for each feature. The widget API handles this cleanly: a plugin adds a widget to the product page, that widget collects customisation input from the customer, and the customisation data travels with the order through the event chain.
{
"id": "customization.engraving",
"name": "Product Engraving",
"entry": "/plugins/customization/engraving/index.js",
"permissions": ["ui:product-page", "storage:local"]
}export const module: PluginModule = {
mount(sdk) {
sdk.widgets.add({
id: 'engraving-widget',
title: 'Add Engraving',
render: EngravingComponent,
});
},
unmount(sdk) {
sdk.widgets.remove('engraving-widget');
},
};The EngravingComponent renders a text input and a preview. When the customer fills it in, the component writes the engraving text to local storage via sdk.services.storage.set, namespaced to the plugin. When checkout:submit fires, the engraving plugin listens and appends the customisation data to the order payload:
sdk.events.on('checkout:submit', (order) => {
const engraving = sdk.services.storage.get<string>('engraving-text');
if (engraving) {
sdk.events.emit('order:customisation-added', {
orderId: order.id,
type: 'engraving',
value: engraving,
});
}
});Conditional product options — size and colour availability, bulk discount tiers — follow the same pattern but require access to product data. Rather than each customisation plugin implementing its own product data fetching, the platform exposes a product data service through the SDK:
const productService = sdk.services.get<ProductService>('products');
const product = await productService.getById(productId);
// Render only the sizes that are in stock
const availableSizes = product.variants
.filter((v) => v.stockLevel > 0)
.map((v) => v.size);This keeps customisation plugins thin: they describe what to show, and the platform's product service determines what is available. A customisation plugin that implements its own inventory logic is duplicating platform infrastructure and will inevitably drift out of sync.
11.4 Third-Party Service Integrations
Analytics, CRM, and email marketing integrations share a common pattern: they need to observe platform events without touching the code that generates them. A purchase completion should trigger a GA4 event, a Mailchimp subscriber update, and a Salesforce opportunity update — but the checkout code should know nothing about any of these systems.
{
"id": "analytics.google",
"name": "Google Analytics Integration",
"entry": "/plugins/analytics/google/index.js",
"permissions": ["events", "api:external"]
}export const module: PluginModule = {
init(sdk) {
sdk.events.on('order:completed', (order) => {
sendEventToGA('purchase', {
transaction_id: order.id,
value: order.total,
currency: order.currency,
items: order.lineItems.map((item) => ({
item_id: item.productId,
item_name: item.name,
price: item.unitPrice,
quantity: item.quantity,
})),
});
});
sdk.events.on('cart:abandoned', ({ cartId, value }) => {
sendEventToGA('begin_checkout', { cart_id: cartId, value });
});
},
};The api:external permission is what enables the call to sendEventToGA, which ultimately reaches Google's measurement endpoint. Without that permission, sdk.services.apiClient would reject any request to an origin not on the approved list. The merchant explicitly grants this permission when installing the plugin, at which point they understand that order data is being sent to Google.
CRM integrations raise a more delicate question: customer data, including email addresses and order history, is sensitive in ways that purchase totals are not. A Salesforce integration plugin needs customer PII to create or update contact records. The permission model should distinguish between analytics data (aggregated, non-identifying) and CRM data (individual, identifying). ShopSphere handles this by requiring a higher-privilege api:customer-data permission for plugins that access individual customer records, and presenting users with a consent prompt that names the destination service:
// CRM plugin requests elevated permission at runtime
const granted = await sdk.permissions.request(
'api:customer-data',
'Salesforce needs your name and email to create a contact record for order tracking.'
);
if (granted) {
sdk.events.on('order:completed', async (order) => {
const customer = await sdk.services.get<CustomerService>('customers')
.getById(order.customerId);
await syncToSalesforce(customer, order);
});
}11.5 Performance and Scalability
An e-commerce platform is one of the more demanding environments for plugin performance, because poor performance is directly measurable in conversion rates. The activation model needs to be deliberate about which plugins load when.
Payment and shipping plugins should load only at checkout — not on the product listing page, not on the cart page. The manifest's activation field (chapter 4) controls this. A payment plugin that declares "activation": { "routes": ["/checkout/*"] } will not be initialised until the customer navigates to the checkout flow. The resource cost of initialising that plugin — the Stripe.js library, the payment form component — is deferred to the moment it is actually needed.
Marketing plugins require the opposite approach in some cases: pop-up promotions and exit-intent offers need to be active from the first page load. But they should yield to the critical path. A plugin that is active on all pages but registers a listener for window.beforeunload to fire an exit-intent event adds essentially no load time. A plugin that loads a 200KB marketing library on every page load is a different matter.
Shipping rate calculators present a specific caching challenge. Carrier APIs are slow — a round trip to FedEx or UPS can take 800ms — and calling them on every product page would make the site feel sluggish. The platform provides a caching layer through the API client, but plugins can also implement their own short-lived caches for frequently-requested rate combinations:
const rateCache = new Map<string, { rates: ShippingRate[]; expiresAt: number }>();
async function getShippingRates(destination: Address, weight: number): Promise<ShippingRate[]> {
const cacheKey = `${destination.postcode}:${weight}`;
const cached = rateCache.get(cacheKey);
if (cached && cached.expiresAt > Date.now()) {
return cached.rates;
}
const rates = await sdk.services.apiClient.post<ShippingRate[]>('/shipping/rates', {
destination,
weight,
});
rateCache.set(cacheKey, {
rates,
expiresAt: Date.now() + 3 * 60 * 1000, // 3-minute TTL
});
return rates;
}A three-minute TTL on shipping rates is a business decision as much as a technical one. Rates rarely change within a session, so serving cached rates is almost always correct. The cache is per-plugin instance, so it is discarded when the plugin is unmounted — no risk of stale rates persisting across sessions.
Mobile performance deserves its own consideration. A shopper on a mid-range mobile device has less CPU headroom than a desktop user. Marketing plugins that are useful to show on desktop — product recommendation overlays, chat widgets, loyalty programme banners — can add enough scripting overhead to measurably degrade mobile checkout completion rates. The platform's activation configuration should allow plugins to declare device-type constraints in their manifest, so a merchant can enable a chat plugin on desktop only without disabling it entirely.
11.6 Vendure: A Production E-commerce Plugin System
ShopSphere is a useful design vehicle, but it is fictional. Vendure is real: a modern, enterprise-grade e-commerce platform built on NestJS and TypeScript, and its plugin system reflects decisions made under real-world constraints. Examining how Vendure differs from the ShopSphere model is instructive.
Explicit Registration Over Runtime Discovery
Vendure does not support dynamic plugin loading. Plugins are declared in a central configuration object that is compiled into the application:
export const config: VendureConfig = {
plugins: [
DefaultSearchPlugin,
AssetServerPlugin.init({ route: 'assets' }),
StripePaymentPlugin.init({ apiKey: process.env.STRIPE_KEY }),
],
};This trades runtime flexibility for compile-time safety. Every plugin is known at build time. The TypeScript compiler validates that AssetServerPlugin.init receives a configuration object that matches its declared type. Adding or removing a plugin requires a redeployment — there is no admin UI to install plugins without a developer's involvement. For enterprise deployments where every plugin is written and reviewed by the development team, this is a reasonable trade. For an open marketplace where merchants install third-party plugins through a dashboard, it is not.
The [object Object] Decorator
Vendure plugins declare their capabilities through a TypeScript decorator, which serves as the plugin's manifest, lifecycle registration, and DI module declaration in one:
@VendurePlugin({
imports: [PluginCommonModule],
providers: [PaymentService],
configuration: (config) => {
config.paymentOptions.paymentMethodHandlers.push(new StripeHandler());
return config;
},
adminApiExtensions: {
schema: gql`
extend type Query {
paymentAnalytics: Analytics
}
`,
resolvers: [PaymentResolver],
},
entities: [PaymentRecord],
compatibility: '^3.0.0',
})
export class StripePaymentPlugin {}The configuration hook runs at bootstrap and mutates the platform configuration before the application starts. The adminApiExtensions field adds new GraphQL queries and mutations to the admin API — the plugin is not just hooking into existing extension points but genuinely extending the API surface. The entities field registers TypeORM entities that Vendure's database migration system will manage. All of this is type-checked: pass a configuration hook with the wrong signature and the TypeScript compiler rejects it before the code runs.
Strategy Pattern for Business Logic
Vendure exposes over fifty pluggable interfaces for customising business logic — payment processing, shipping calculation, tax computation, search indexing, asset storage, and more. Each strategy follows the same structure: a typed interface with init and optional destroy methods that receive an Injector for accessing the DI container:
export class S3AssetStorageStrategy implements AssetStorageStrategy {
private s3: S3Client;
async init(injector: Injector) {
this.connection = injector.get(TransactionalConnection);
await this.initializeS3Client();
}
async writeFileFromBuffer(fileName: string, data: Buffer): Promise<string> {
await this.s3.send(new PutObjectCommand({
Bucket: this.options.bucket,
Key: fileName,
Body: data,
}));
return `https://${this.options.bucket}.s3.amazonaws.com/${fileName}`;
}
async destroy() {
await this.s3.destroy();
}
}The Injector gives the strategy access to the full DI container — database connections, configuration, other services — without coupling the strategy to how those services are constructed. Testing the strategy means constructing it with a mock injector. The contract — "implement these methods, and the platform will call them at the right times" — is the same pattern discussed in chapter 7, applied to a real platform with a deep catalogue of extension points.
Schema and Data Model Extension
Vendure allows plugins to extend the GraphQL API and database schema without forking the core. Custom fields can be added to core entities through configuration:
config.customFields.Product.push({
name: 'warrantyPeriod',
type: 'int',
label: [{ languageCode: LanguageCode.en, value: 'Warranty (months)' }],
ui: { component: 'number-input' },
});And plugins can define new entity types that participate in Vendure's ORM:
adminApiExtensions: {
schema: gql`
extend type Query { productAnalytics(id: ID!): ProductAnalytics }
type ProductAnalytics { views: Int! conversionRate: Float! revenue: Money! }
`,
resolvers: [ProductAnalyticsResolver],
}
@Entity()
class ProductReview extends VendureEntity {
@ManyToOne(type => Product) product: Product;
@Column() rating: number;
@Column('text') comment: string;
}This level of depth — extending the database schema, extending the API surface, contributing new resolvers — is possible only because Vendure treats plugins as trusted first-party code running in the same process with full access to the DI container. The ShopSphere model, with its runtime loading and permission-gated SDK, achieves broader extensibility but at the cost of this depth.
What Vendure's Trade-offs Reveal
Vendure is not a less secure or less capable system than ShopSphere's dynamic model — it is a differently scoped one. By treating all plugins as vetted first-party code, Vendure can offer deep integration: full database access, GraphQL schema extension, NestJS DI. By requiring redeployment for plugin changes, it eliminates an entire class of runtime security problems. The compatibility validation through compatibility: '^3.0.0' is the primary safety mechanism, not sandboxing.
The lesson is that the right plugin architecture depends on who writes the plugins. When the answer is "the same team that writes the platform code, after a careful review process", Vendure's model is appropriate and significantly simpler to implement. When the answer is "any merchant who clicks Install in a marketplace", you need the runtime loading, permission grants, and sandboxing that ShopSphere requires.
Conclusion
E-commerce exposes the full breadth of plugin architecture decisions. Payment plugins reveal the intersection of security and compliance — PCI DSS shapes not just the implementation but the permission model, the sandbox boundaries, and how payment data moves through the system. Product customisation shows how widget systems and event chains let plugins enrich the shopping experience without coupling to the product page's internals. Third-party integrations demonstrate why event-driven communication is the right model for analytics and CRM: the checkout code emits events into a channel; who receives those events, and what they do with them, is not the checkout's concern.
The comparison between ShopSphere and Vendure makes the core trade-off concrete. Runtime plugin loading with sandboxing and permission checking enables an open marketplace but limits the depth of integration each plugin can achieve. Static registration with trusted first-party code enables deep integration — database access, API extension, full DI container — but requires redeployment for every plugin change. Neither is wrong. They answer different questions about who the plugin authors are and what they need to be able to do.
In the next chapter, we apply the same thinking to a Content Management System, where the extensibility requirements are different again: editor integrations, content type definitions, and the particular challenge of plugins that operate on structured content at editorial time rather than purchase time.