Vendure Engineering Principles

[martijnvdbrug]

We need your input!

Since Vendure focuses on developer happiness, we'd like to introduce an 'Engineering Principles' section in the docs. This should help developers make design choices when implementing custom functionality in Vendure.

Checkout GitLab's example, or Zalando's Engineering Principles.

What are your best practices?

What best practices do you use when developing custom functionality in Vendure?**

• It should be an un-opinionated best practice for everyone. If you prefer const => {} instead of function, that's fine, but shouldn't really be in the Vendure Engineering Principles
• It should be related to Vendure

This is just the initial setup, it will be a dynamic document, where contributors can create PR's to discus new best practices before they can be added.

(thumbs up on the comment if you like a proposal)

[martijnvdbrug]

Proposal: Prefer Vendure Services over the use of TransactionalConnection

Vendure's services hold logic. When using TransactionalConnection, logic like translation and price applying is skipped. Benefits

• Don't have to apply logic from services yourself
• Upgrade proof: When upgrading to a newer Vendure version, logic will be added in Services. You will be missing out on that if you use TransactionalConnection

You might use TransactionalConnection if:

1. You only need specific fields internally, in code, not returning it as Graphql result.
2. You need to optimize for performance, and service logic is too heavy

[brunoslalmeida]

List of available services to use :)

https://github.com/vendure-ecommerce/vendure/tree/master/packages/core/src/service/services

[brunoslalmeida]

Example of use:

import {
SellerService,
ChannelService,
...
} from "@vendure/core";

 const seller = await this.sellerService.create(ctx, args.input);
 const name = normalizeString(seller.name, "-");

 const defaultChannel = await this.channelService.getDefaultChannel(ctx);
 const channel = await this.channelService.create(ctx, {
   code: seller.name,
   sellerId: seller.id,
   token: `${name}-token`,
   currencyCode: defaultChannel.defaultCurrencyCode,
   defaultLanguageCode: defaultChannel.defaultLanguageCode,
   pricesIncludeTax: defaultChannel.pricesIncludeTax,
   defaultShippingZoneId: defaultChannel.defaultShippingZone.id,
   defaultTaxZoneId: defaultChannel.defaultTaxZone.id,
 });

[martijnvdbrug]

Great idea. Maybe we can do something like Vue style guide, with a good example and a bad.
Something like

- const product = await this.transactionalConnection.getRepository(ctx, Product).findOne({where: {id}});
+ const product = await this.productService.findOne(ctx, id);

[michaelbromley]

Plugins as the basic unit of extension

You should aim to structure your application as a set of plugins. Each plugin should be concerned with a specific feature set or unit of functionality. For instance, each of the following would be implemented as a separate plugin:

• wishlists
• loyalty points
• product recommendations
• sitemap generation
• stock level sync to backoffice

Benefits

Although it is possible to implement a lot of customization by simply adding stuff to the main VendureConfig, encapsulating them in plugins has the following benefits:

1. Your code will be better organized. All the resolvers, services, entities, config and ui extensions related to e.g. wishlists are all housed in the same directory.
2. Plugins are often a hard requirement. While most of Vendure's extensibility is accessible via the VendureConfig object, certain common tasks can only be done via plugins, such as extending the GraphQL APIs, adding REST endpoints, using the EventBus, defining job queues.
3. Your features will scale better. For example, a "recommendations" feature might start off as nothing more than a custom field definition allowing products to link to other products. Putting this into a plugin means that in future, when you want to add capabilities to the recommendations such as custom UI, automation via event bus subscriptions etc, you already know where to put everything.
4. Your plugins will be more easily tested. Creating an e2e test suite for just the functionality of that particular plugin is as simple as adding that plugin to the test server config.
5. You can share your plugins. If you ever want to share the functionality with other projects, it's already arranged in a self-contained package.

The BasePlugin pattern

Some configuration & extension doesn't really fall neatly into a single "feature". For instance

• setting the EntityIdStrategy
• defining custom CollectionFilters
• defining custom PromotionActions
• defining the basic OrderProcess configuration required by the business itself

These types of "global" config could justifiably live at the top-level of the app and go directly in the VendureConfig. However, another approach is to create a BasePlugin which handles all of this required config. The reasoning is the same as listed in the "benefits" with regards to code organization, scaling, testability.

[martijnvdbrug]

100% agree on the plugins! Makes project maintenance so much easier and predictable, especially when you are managing multiple projects that are using the same plugins.

I still have to get used to the BasePlugin pattern though. We usually try to do these things either in reusable plugins (e.g for generic promotions actions) or just put them in the vendure-config and e2e test the project. That said, I am not opposed, and will try this soon!

[michaelbromley]

Yeah, I'd say BasePlugin doesn't really qualify for "best practice" status yet. I'm personally using it but I see it more of a suggestion right now. I'm interested to hear more perspectives from other devs.

[brunoslalmeida]

I am currently using the baseplugin approach for my business needs. To streamline the process, I'm trying to remove function plugins like shipping and payment, making them available only when ready. I do agree with your idea of base plugin + functional plungins :)

[martijnvdbrug]

@michaelbromley it can still be in there. I like how Vue Style Guid does it, they have different levels of rules:

• Priority A: Essential
• Priority B: Strongly Recommended
• Priority C: Recommended

[martijnvdbrug]

Use history entries

Give administrators more insight in whats happening by logging events as order or customer history entries. Some examples that might be useful for your administrators:

• Confirmation email sent to martijn@example.io
• Order sent to Fulfillment platform X with id 123
• Invoice 1234 generated

This can save you, the developer, quite some support questions. Admins can look up this information themselves, and you don't have to check server logs.

[brunoslalmeida]

It would be awesome to log the query and mutations received. It could at debug log level.