The heart of Vendure is its plugin system. Plugins not only allow you to instantly add new functionality to your Vendure server via third-party npm packages, they are also the means by which you build out the custom business logic of your application.
Plugins in Vendure allow one to:
… and more!
In a typical Vendure application, custom logic and functionality is implemented as a set of plugins which are usually independent of one another. For example, there could be a plugin for each of the following: wishlists, product reviews, loyalty points, gift cards, etc. This allows for a clean separation of concerns and makes it easy to add or remove functionality as needed.
If you use AI coding agents when developing plugins, see the AI-assisted development guide.
Vendure provides a set of core plugins covering common functionality such as assets handling, email sending, and search. For documentation on these, see the Core Plugins reference.
Here's a bare-minimum example of a plugin:
This plugin does one thing only: it adds a new custom field to the Customer entity.
The plugin is then imported into the VendureConfig:
The key feature is the decorator, which marks the class as a Vendure plugin and accepts a configuration object on the type .
@VendurePlugin()A VendurePlugin is actually an enhanced version of a NestJS Module, and supports all the metadata properties that NestJS modules support:
imports: Allows importing other NestJS modules in order to make use of their exported providers.providers: The providers (services) that will be instantiated by the Nest injector and that may
be shared across this plugin.controllers: Controllers allow the plugin to define REST-style endpoints.exports: The providers which will be exported from this plugin and made available to other plugins.Additionally, the VendurePlugin decorator adds the following Vendure-specific properties:
configuration: A function which can modify the VendureConfig object before the server bootstraps.shopApiExtensions: Allows the plugin to extend the GraphQL Shop API with new queries, mutations, resolvers & scalars.adminApiExtensions: Allows the plugin to extend the GraphQL Admin API with new queries, mutations, resolvers & scalars.entities: Allows the plugin to define new database entities.compatibility: Allows the plugin to declare which versions of Vendure it is compatible with.Since a Vendure plugin is a superset of a NestJS module, this means that many NestJS modules are actually valid Vendure plugins!
Since a VendurePlugin is built on top of the NestJS module system, any plugin (as well as any providers it defines) can make use of any of the NestJS lifecycle hooks:
Note that lifecycle hooks are run in both the server and worker contexts. If you have code that should only run either in the server context or worker context, you can inject the ProcessContext provider.
A plugin can implement these hooks directly, rather than only on the providers it defines:
If that startup work needs to call Vendure's services, it will need a RequestContext, which
outside of the request-response cycle you create yourself — see
Creating a RequestContext,
including how to give it a user so that permission checks pass.
Another hook that is not strictly a lifecycle hook, but which can be useful to know is the configure method which is
used by NestJS to apply middleware. This method is called only for the server and not for the worker, since middleware relates
to the network stack, and the worker has no network part.
Run the npx vendure add command, and select "Create a new Vendure plugin".
This will guide you through the creation of a new plugin and automate all aspects of the process.
This is the recommended way of creating a new plugin.
Although the Vendure CLI is the recommended way to create a new plugin, it can be useful to understand the process of creating a plugin manually.
Vendure plugins are used to extend the core functionality of the server. Plugins can be pre-made functionality that you can install via npm, or they can be custom plugins that you write yourself.
For any unit of functionality that you need to add to your project, you'll be creating a Vendure plugin. By convention, plugins are stored in the plugins directory of your project. However, this is not a requirement, and you are free to arrange your plugin files in any way you like.
For a complete working example of a Vendure plugin, see the real-world-vendure Reviews plugin
You can also use the Vendure CLI to quickly scaffold a new plugin.
In this guide, we will implement a simple but fully-functional wishlist plugin step-by-step. The goal of this plugin is to allow signed-in customers to add products to a wishlist, and to view and manage their wishlist.
We'll start by creating a new directory to house our plugin, add create the main plugin file:
The PluginCommonModule will be required in all plugins that you create. It contains the common services that are exposed by Vendure Core, allowing you to inject them into your plugin's services and resolvers.
Next we will define a new database entity to store the wishlist items. Vendure uses TypeORM to manage the database schema, and an Entity corresponds to a database table.
First let's create the file to house the entity:
By convention, we'll store the entity definitions in the entities directory of the plugin. Again, this is not a requirement, but it is a good way to keep your plugin organized.
Let's break down what's happening here:
WishlistItem entity extends the VendureEntity class. This is a base class which provides the id, createdAt and updatedAt fields, and all custom entities should extend it.@Entity() decorator marks this class as a TypeORM entity.@ManyToOne() decorator defines a many-to-one relationship with the ProductVariant entity. This means that each WishlistItem will be associated with a single ProductVariant.productVariantId column is not strictly necessary, but it allows us to always have access to the ID of the related ProductVariant without having to load the entire ProductVariant entity from the database.constructor() is used to create a new instance of the entity. This is not strictly necessary, but it is a good practice to define a constructor which takes a DeepPartial of the entity as an argument. This allows us to create new instances of the entity using the new keyword, passing in a plain object with the desired properties.Next we need to register this entity with our plugin:
We'll now define a new custom field on the Customer entity which will store a list of WishlistItems. This will allow us to easily query for all wishlist items associated with a particular customer.
Custom fields are defined in the VendureConfig object, and in a plugin we use the configuration function to modify the config object:
In this snippet we are pushing a new custom field definition onto the Customer entity's customFields array, and defining this new field as a list (array) of WishlistItem entities. Internally, this will tell TypeORM to update the database schema to store this new field. We set internal: true to indicate that this field should not be directly exposed to the GraphQL API as Customer.customFields.wishlistItems, but instead should be accessed via a custom resolver we will define later.
In order to make use of this custom field in a type-safe way, we can tell TypeScript about this field in a new file:
We can then import this types file in our plugin's main file:
Custom fields are not solely restricted to Vendure's native entities though, it's also possible to add support for custom fields to your own custom entities. This way other plugins would be able to extend our example WishlistItem. See: Supporting custom fields
A "service" is a class which houses the bulk of the business logic of any plugin. A plugin can define multiple services if needed, but each service should be responsible for a single unit of functionality, such as dealing with a particular entity, or performing a particular task.
Let's create a service to handle the wishlist functionality:
Let's break down what's happening here:
WishlistService class is decorated with the @Injectable() decorator. This is a standard NestJS decorator which tells the NestJS dependency injection (DI) system that this class can be injected into other classes. All your services should be decorated with this decorator.connection argument is a TransactionalConnection instance, which is used to access and manipulate data in the database. The ProductVariantService argument is a built-in Vendure service which contains methods relating to ProductVariants.RequestContext object is usually the first argument to any service method, and contains information and context about the current request as well as any open database transactions. It should always be passed to the methods of the TransactionalConnection.The service is then registered with the plugin metadata as a provider:
This plugin will need to extend the Shop API, adding new mutations and queries to enable the customer to view and manage their wishlist.
First we will create a new file to hold the GraphQL schema extensions:
The graphql-tag package is a dependency of the Vendure core package. Depending on the package manager you are using, you may need to install it separately with yarn add graphql-tag or npm install graphql-tag.
The api-extensions.ts file is where we define the extensions we will be making to the Shop API GraphQL schema. We are defining a new WishlistItem type; a new query: activeCustomerWishlist; and two new mutations: addToWishlist and removeFromWishlist. This definition is written in schema definition language (SDL), a convenient syntax for defining GraphQL schemas.
Next we need to pass these extensions to our plugin's metadata:
Now that we have defined the GraphQL schema extensions, we need to create a resolver to handle the new queries and mutations. A resolver in GraphQL is a function which actually implements the query or mutation defined in the schema. This is done by creating a new file in the api directory:
Resolvers are usually "thin" functions that delegate the actual work to a service. Vendure, like NestJS itself, makes heavy use of decorators at the API layer to define various aspects of the resolver. Let's break down what's happening here:
@Resolver() decorator tells the NestJS DI system that this class is a resolver. Since a Resolver is part of the NestJS DI system, we can also inject dependencies into its constructor. In this case we are injecting the WishlistService which we created in the previous step.@Mutation() decorator tells Vendure that this is a mutation resolver. Similarly, @Query() decorator defines a query resolver. The name of the method is the name of the query or mutation in the schema.@Transaction() decorator tells Vendure that this resolver method should be wrapped in a database transaction. This is important because we are performing multiple database operations in this method, and we want them to be atomic.@Allow() decorator tells Vendure that this mutation is only allowed for users with the Owner permission. The Owner permission is a special permission which indicates that the active user should be the owner of this operation.@Ctx() decorator tells Vendure that this method requires access to the RequestContext object. Every resolver should have this as the first argument, as it is required throughout the Vendure request lifecycle.This resolver is then registered with the plugin metadata:
More information about resolvers can be found in the NestJS docs.
Since Vendure v2.0.0, it is possible for a plugin to specify which versions of Vendure core it is compatible with. This is especially important if the plugin is intended to be made publicly available via npm or another package registry.
The compatibility is specified via the compatibility property in the plugin metadata:
The value of this property is a semver range which specifies the range of compatible versions. In this case, we are saying that this plugin is compatible with any version of Vendure core which is >= 2.0.0 < 3.0.0.
The final step is to add the plugin to the VendureConfig object. This is done in the vendure-config.ts file:
Now that the plugin is installed, we can test it out. Since we have defined a custom field, we'll need to generate and run a migration to add the new column to the database.
Generate the Migration File
Run the following command to generate a migration file for the wishlist-plugin:
When prompted, select the "Generate a new migration" option. This will create a new migration file in the src/migrations folder.
After generating the migration file, apply the changes to the database by running the same command again:
Then start the server:
Once the server is running, we should be able to log in as an existing Customer, and then add a product to the wishlist:
We can then query the wishlist items:
And finally, we can test removing an item from the wishlist:
If you have created a plugin that you would like to share with the community, you can publish it to npm, and even have it listed on the Vendure Hub.
For a full guide to publishing plugins, see the Publishing a Plugin how-to guide.
Architecture reviews, custom plugin work, migrations, ongoing support. Get a hand from the team that builds Vendure.
Talk to the team