Vendure's plugin-based architecture means you'll be writing a lot of plugins. Some of those plugins may be useful to others, and you may want to share them with the community.
We have created Vendure Hub as a central listing for high-quality Vendure plugins.
This guide will walk you through the process of publishing a plugin to npm and submitting it to Vendure Hub.
There are a couple of ways you can structure your plugin project:
We recommend that you use a "monorepo" structure to develop your plugins. This means that you have a single repository which contains all your plugins, each in its own subdirectory. This makes it easy to manage dependencies between plugins, and to share common code such as utility functions & dev tooling.
Even if you only have a single plugin at the moment, it's a good idea to set up your project in this way from the start.
To that end, we provide a monorepo plugin starter template which you can use as a starting point for your plugin development.
This starter template includes support for:
We recommend that you use scoped packages for your plugins, which means
they will be named like @<scope>/<plugin-name>. For example, if your company is called acme, and you are publishing a plugin that
implements a loyalty points system, you could name it @acme/vendure-plugin-loyalty-points.
Your plugin should not include Vendure packages as dependencies in the package.json file. You may declare them as a peer dependencies, but this is not
a must. The same goes for any of the transitive dependencies of Vendure core such as @nestjs/graphql, @nestjs/common, typeorm etc. You can assume
that these dependencies will be available in the Vendure project that uses your plugin.
As for version compatibility, you should use the compatibility property in your plugin definition to ensure that the Vendure project is using a compatible version of Vendure.
You are free to license your plugin as you wish. Although Vendure itself is licensed under the GPLv3, there is a special exception for plugins which allows you to distribute them under a different license. See the plugin exception for more details.
Once your plugin is ready, you can publish it to npm. This is covered in the npm documentation on publishing packages.
Vendure Hub is a curated list of high-quality plugins. To be accepted into Vendure Hub, we require some additional requirements be satisfied.
Your plugin package must include a CHANGELOG.md file which looks like this:
The exact format of the entries is up to you - you can e.g. use Keep a Changelog format, grouping by type of change, using tooling
to help generate the entries, etc. The important thing is that the CHANGELOG.md file is present and up-to-date, and published as part of your
package by specifying it in the files field of your package.json file.
Vendure Hub will read the contents of your changelog to display the latest changes in your plugin listing.
Good documentation is a key criteria for acceptance into Vendure Hub.
Your plugin package must include a README.md file which contains full instructions on how to install and use your plugin. Here's a template you can use:
All publicly-exposed services, entities, strategies, interfaces etc should be documented using JSDoc comments. Not only does this improve the developer experience for your users, but it also allows Vendure Hub to auto-generate documentation pages for your plugin.
Here are some examples of well-documented plugin code (implementation details omitted for brevity):
@category Plugin. This will be used when generating the docs pages to group plugins together..init() method is the thing that users will call to configure the plugin. Document this method with an example of how to use it.@internal.Testing is an important part of ensuring the quality of your plugin, as well as preventing regressions when you make changes.
For plugins of any complexity, you should aim to have a suite of end-to-end tests as covered in the testing docs.
In future we may use the test results to help determine the quality of a plugin.
Once your plugin is published to npm and satisfies the requirements above, you can submit it to Vendure Hub via our contact form, making sure to include a link to the npm package and the GitHub repository.
Vendure Hub supports the listing of paid plugins. If you would like to sell plugins through Vendure Hub, please contact us and provide details about the plugins you would like to sell.
Architecture reviews, custom plugin work, migrations, ongoing support. Get a hand from the team that builds Vendure.
Talk to the team