Use npx vendure add to easily add a new entity to a plugin.
Your plugin can define new database entities to model the data it needs to store. For instance, a product review plugin would need a way to store reviews. This would be done by defining a new database entity.
This example shows how new TypeORM database entities can be defined by plugins.
If your tsconfig.json uses "target": "ES2022" or later (including Node.js v24+), you must also set "useDefineForClassFields": false.
Without this setting, ES2022 class field semantics cause entity fields to be overwritten with undefined after the constructor runs, resulting in "null value in column violates not-null constraint" database errors.
See the TypeScript documentation for more details.
Any custom entities must extend the VendureEntity class.
In this example, we are making use of the following TypeORM decorators:
@Entity() - defines the entity as a TypeORM entity. This is required for all entities. It tells TypeORM to create a new table in the database for this entity.@Column() - defines a column in the database table. The data type of the column is inferred from the TypeScript type of the property, but can be overridden by passing an options object to the decorator. The @Column() also supports many other options for defining the column, such as nullable, default, unique, primary, enum etc.@ManyToOne() - defines a many-to-one relationship between this entity and another entity. In this case, many ProductReview entities can be associated with a given Product. There are other types of relations that can be defined - see the TypeORM relations docs.There is an additional Vendure-specific decorator:
@EntityId() marks a property as the ID of another entity. In this case, the productId property is the ID of the Product entity. The reason that we have a special decorator for this is that Vendure supports both numeric and string IDs, and the @EntityId() decorator will automatically set the database column to be the correct type. This productId is not necessary, but it is a useful convention to allow access to the ID of the associated entity without having to perform a database join.The new entity is then passed to the entities array of the VendurePlugin metadata:
Once you have added a new entity to your plugin, and the plugin has been added to your VendureConfig plugins array, you must create a database migration to create the new table in the database.
The new entity can now be used in your plugin code. For example, you might want to create a new product review when a customer submits a review via the storefront:
In addition to the decorators described above, there are many other decorators provided by TypeORM. Some commonly used ones are:
There is also another Vendure-specific decorator for representing monetary values specifically:
@Money(): This works together with the MoneyStrategy to allow configurable control over how monetary values are stored in the database. For more information see the Money & Currency guide.The full list of TypeORM decorators can be found in the TypeORM decorator reference
Once you have defined a new DB entity, it is likely that you want to expose it in your GraphQL API. Here's how to define a new type in your GraphQL API.
In case you'd like to make the ProductReview entity support content in multiple languages, here's how to implement the Translatable Interface.
In case you'd like to support separate ProductReview entities per Channel, here's how to implement the ChannelAware Interface.
Just like you can extend Vendures native entities like Product to support your custom needs, you may enable other developers to extend your custom entities too! Here's how to implement the HasCustomFields Interface.
Architecture reviews, custom plugin work, migrations, ongoing support. Get a hand from the team that builds Vendure.
Talk to the team