Implementing HasCustomFields

From Vendure v2.2, it is possible to add support for custom fields to your custom entities. This is useful when you are defining a custom entity as part of a plugin which is intended to be used by other developers. For example, a plugin which defines a new entity for storing product reviews might want to allow the developer to add custom fields to the review entity.

Defining entities that support custom fields

First you need to update your entity class to implement the HasCustomFields interface, and provide an empty class which will be used to store the custom field values:

src/plugins/reviews/entities/product-review.entity.ts

import {
    DeepPartial,
    HasCustomFields,
    Product,
    VendureEntity,
    ID,
    EntityId,
} from '@vendure/core';
import { Column, Entity, ManyToOne } from 'typeorm';

export class CustomProductReviewFields {}

@Entity()
export class ProductReview extends VendureEntity implements HasCustomFields {
    constructor(input?: DeepPartial<ProductReview>) {
        super(input);
    }

    @Column(() => CustomProductReviewFields)
    customFields: CustomProductReviewFields;
    
    @ManyToOne(() => Product)
    product: Product;

    @EntityId()
    productId: ID;

    @Column()
    text: string;

    @Column()
    rating: number;
}

Type generation

Given the above entity your API extension might look like this:

type ProductReview implements Node {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime!

  product: Product!
  productId: ID!
  text: String!
  rating: Int!
}

input CreateProductReviewInput {
  productId: ID!
  text: String!
  rating: Int!
}

input UpdateProductReviewInput {
  id: ID!
  productId: ID
  text: String
  rating: Int
}

Notice the lack of manually defining customFields on the types, this is because Vendure extends the types automatically once your entity implements HasCustomFields.

Naming convention

In order for Vendure to find the correct input types to extend to, they must conform to the naming convention of Create<EntityName>Input and Update<EntityName>Input.

Following this caveat, codegen will now produce correct types including customFields-fields like so:

export type ProductReview = Node & {
  customFields?: Maybe<Scalars['JSON']['output']>;
  // Note: Other fields omitted for brevity
}

export type CreateProductReviewInput = {
  customFields?: InputMaybe<Scalars['JSON']['input']>;
  // Note: Other fields omitted for brevity
}

export type UpdateProductReviewInput = {
  customFields?: InputMaybe<Scalars['JSON']['input']>;
  // Note: Other fields omitted for brevity
}

Supporting custom fields in your services

Creating and updating your entity works now by setting the fields like usual, with one important addition being, you mustn't forget to update relations via the CustomFieldRelationService. This is needed because a consumer of your plugin may extend the entity with custom fields of type relation which need to get saved separately.

src/plugins/reviews/services/review.service.ts

import { Injectable } from '@nestjs/common';
import { RequestContext, Product, TransactionalConnection, CustomFieldRelationService } from '@vendure/core';

import { ProductReview } from '../entities/product-review.entity';

@Injectable()
export class ReviewService {
    constructor(
      private connection: TransactionalConnection,
      private customFieldRelationService: CustomFieldRelationService,
    ) {}

    async create(ctx: RequestContext, input: CreateProductReviewInput) {
        const product = await this.connection.getEntityOrThrow(ctx, Product, input.productId);
        // You'll probably want to do more validation/logic here in a real world scenario
        
        const review = new ProductReview({ ...input, product });
        const savedEntity = await this.connection.getRepository(ctx, ProductReview).save(review);
        await this.customFieldRelationService.updateRelations(ctx, ProductReview, input, savedEntity);

        return savedEntity;
    }
}

Updating config

Now you'll be able to add custom fields to the ProductReview entity via the VendureConfig:

src/vendure-config.ts

import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
    // ...
    customFields: {
        ProductReview: [
            { name: 'reviewerName', type: 'string' },
            { name: 'reviewerLocation', type: 'string' },
        ],
    },
};

Migrations

Extending entities will alter the database schema requiring a migration. See the migrations guide for further details.