Announcing Vendure v2.1

Vendure is an open-source platform for building ambitious commerce applications. Since our groundbreaking v2.0 release back in June, we've been hard at work on some huge new features which we are excited to share in today's announcement.

The keynote of this release is making Vendure even more accessible: new languages, new framework support, new documentation. Let's take a look at what's new!

New documentation

It all starts with the docs. If developers can't learn it, they won't use it. The Vendure documentation comprises over 700 pages of source-generated API docs and hand-written guides. Up till now we've been using a custom solution built on Hugo. While Hugo is an excellent, lightning-fast site generator, the golang templating made customization slow and frustrating. As a result, the design was rarely updated, and we lacked features such as dark/light mode and full-text search. Moreover, after surveying our community we found that our docs were sometimes lacking context and high-level explanations of the main concepts, as well as step-by-step, practical guides for specific common tasks. Hearing stories of developers struggling to understand Vendure was painful!

We decided to fix all of this and more and embarked on a complete re-write of our documentation. We spent over 200 hours building, writing, and illustrating the beautiful new docs that we are releasing today.

Our new docs are built on Docusaurus, which is a much better fit for our TypeScript-based codebase and community. Content-wise, we have nearly doubled the amount of content, covering core concepts, developer guides, how-to guides; ranging from introductory articles to in-depth explorations of our API. We now have over 100 diagrams and illustrations, and - best of all - we've included embedded API playgrounds and runnable StackBlitz examples throughout the docs. The search experience has also been massively upgraded - we now have a lightning-fast full-text search built on Typesense.

All of this is aimed at making Vendure more accessible for both new and seasoned Vendure developers to rapidly find, learn, and understand our APIs.

New UI extensibility

Our Admin UI features a powerful extension mechanism allowing developers to define custom routes and components which expose new functionality. In v2.1 we have worked hard to make it even easier to create extensions by radically simplifying the extension APIs as well as adding native support for components authored in React.

React support

This is a big one! Our Admin UI is built on Angular - a solid, performant and maintainable framework that has served us well for many years. But it is clear that the majority of developers are more familiar with React, so the requirement to author UI extensions in Angular has long been a source of friction for some Vendure developers. With v2.1, you can now build your custom components in React. And those React components will run directly and seamlessly in the UI app - no iframes - and therefore have access to the full range of internal services (e.g. notifications, data fetching) that Angular components enjoy.

Furthermore we have introduced a set of dedicated React components and hooks to allow you to build seamless integrations.

Our new documentation includes examples in both Angular and React now. Here's an illustration showing a component implemented in both frameworks:

Simplified APIs

Whether building in Angular or React, our APIs for extending the Admin UI have been vastly simplified. Previously, there was a lot of boilerplate required around setting up multiple Angular modules, with internal implementation concerns leaking out into our public APIs. This made even simple extensions - such as adding a new navigation item - much more complex than necessary. In v2.1 we set out to distill these APIs down to their essentials, and remove the need to understand anything about the underlying Angular module system.

This was made possible by recent advances in Angular - notably their new stand-alone component approach - which means you no longer need to use Angular modules at all. If you are building UI extensions in React, you will not need to touch any Angular APIs whatsoever. We've encapsulated all of the underlying implementation details behind a set of simple, coherent functions.

Here's a before & after comparison:

Any existing UI extensions will still work as before, but you can start to migrate to the new APIs by following this guide.

Customize data tables

Our powerful data table component drives all this list views in the Vendure Admin UI. With v2.1 you can now provide custom components - written in either Angular or React - to render any column. For instance, you could render a product slug as a link to your storefront url, or render a colour-coded status badge for a custom field.

Combined with custom fields, which feature sorting & filtering out of the box, this unlocks some very powerful possibilities for modelling and interacting with custom data.

See the new docs on custom data table components.

New translations & RTL support

Vendure is a global platform. Developers from all over the world use our native localization support to build applications that serve customers across multiple languages, locales and currencies. Part of that is making our Admin UI accessible to as many people as possible via our community-contributed translations.

Thanks to our wonderful global community, we have expanded our range of translations of our Admin UI to include four new languages: Arabic, Hebrew, Persian & Nepali, bringing the total to 17 and making our Admin UI newly accessible to around 250 million more people. This was more than just a new set of translation files though: Arabic, Hebrew and Persian are right-to-left languages, which means we also had to implement right-to-left support in the UI. This means that most of the visual idioms of left-to-right layouts get reversed - the main menu moves to the right of the screen, breadcrumbs are reversed, etc.

Here's a comparison between a left-to-right layout in German, and the same screen in Arabic:

Data table filter presets

The powerful filtering capabilities of our UI data tables allow users to find the exact set of data they need. With v2.1 we've added the ability to save any combination of filters as a preset, which then allows you to instantly switch to those filters in a single click.

We've also added the ability to filter by relative date, as in "show me all orders placed in the past 7 days". With these new features, you can for instance create a "Recent orders" preset like this:

Introducing the Vendure CLI

Last but not least, we're excited to announce the release of a brand-new CLI tool to boost your productivity when building Vendure apps. This initial release includes an automation for the most common yet time-consuming task: scaffolding a new plugin. No more copy-paste-rename tedium. Just one command, a handful of prompts, and boom! You have a new plugin set up following best practices, all wired up and ready to be filled out with your custom business logic.

In future we'll expand the range of tasks that the CLI can perform. Let us know what we should handle next!

Other notable changes

Here's a non-exhaustive list of other cool stuff in this release:

• We've made numerous improvements to the BullMQJobQueuePlugin, fixing long-standing issues with inaccurate job lists as well as setting default expiry limits on completed jobs to prevent

• Custom field relations can now define an inverseSide property, unlocking cleaner, more powerful access patterns.

• Our Stripe payments integration now allows you full control of what custom data to send to Stripe when creating a Payment Intent or a new Customer.

• The ProductVariantPriceCalculationStrategy can now make calculations based on the product variant properties, unlocking new, more sophisticated ways of calculating dynamic pricing.

• Promotions have a new usageLimit field which allows you to specify an overall (not customer-specific) limit on the number of times a promotion may be used.

• Most underlying dependencies, including NestJS and Apollo Server, have been updated to the latest major versions.

• The rest of the new features and fixes can be found in the changelog.

Breaking Changes

Although this is a minor release, and no breaking changes have been made to the public Vendure APIs, the upgrade of Apollo Server from v3 to v4 may be a breaking change in the rare case that you have defined a custom ApolloServerPlugin in your app. Those changes are covered in the Apollo Server migration guide.

The new Promotion.usageLimit field will require a non-destructive database migration to be performed. You should not need to do any manual migration work - it is a straightforward addition of a field to a table.

In the Admin UI, the "stock locations" list and detail views have been moved from the "catalog" module to the "settings" module. Also, the menu item & breadcrumb for "inventory" has been renamed to "products". This is an end-user breaking change rather than a code breaking change. Any UI extensions that link to a /catalog/inventory/... route will still work as there is a redirect in place to catalog/products/....

The ForbiddenError now defaults to a "warning" rather than "error" log level. Previously this was causing too much noise in logging services and the new level better reflects the severity of the error.

Thank you, Vendure community!

Lastly I'd like to personally thank everyone who contributed to this massive release. From issues and pull requests, to feedback on our new docs, to expertise in implementing RTL support, to supporting one another in our Discord server - Vendure would simply not be what it is today without our community.

In particular I'd like to acknowledge the following people who made direct code contributions to this release:

Alessio M, Alexis Kobrinski, Alexis Vigoureux, Andreas Sonnleitner, BeepLoveKarki, cdiban, Daniel Biegler, Denis, Dushko Jordanovski, Eusebio Trigo, Gautier Darchen, Giosue Delgado, Goro, Hiago Alves, Hosein Ghanbari, Jacob Frantz, Jean-Baptiste Alleaume, Kolja Martens, Martijn van de Brug, Mizan3050, oidt, Patrick A Lima, Pieter Doms, PKarics, Sagi Rorlich, Serge Morel, Tarik, yasserlens