Skip to main content

Storefront - Enterprise Contracts

What is a contract

Contracts allow you to validate disjointed communication between two consumers of a given service. Contracts are commonly used to allow servers and consumers of an API to validate and handle changes to that API. This technique has been adapted for TypeScript consumers of Storefront - Enterprise to handle communication of changes between our internal elements to your external elements.

While the consumption of contracts is optional, we highly encourage it to make your components more resilient to any changes from our internal structure.

Contracts in Storefront - Enterprise

We define general contracts in @boldpenguin/sdk-types and component contracts in @boldpenguin/sdk-types/dist/components. These Typescript interfaces define all the properties and types we use on our components as inputs.

Example usage

import { IDateInputComponent } from '@boldpenguin/sdk-types';

class BpSdkExternalDateInput implements IDateInputComponent {
}

Validating attributes

Notably, these contracts only allow you to track properties. With a bit more work you can start tracking attributes as well, making your external components resilient to our internal component changes. When registering web components, there is a defined observedAttributes property you can use to look at all the attributes a component consumes. You can validate the attributes match by comparing the external and internal components.

Jest example

expect(customElements.get('bp-sdk-date-input').observedAttributes.sort()).toEqual(customElements.get('bp-sdk-external-date-input').observedAttributes.sort());

Dynamic example

  isValidComponent(tag: string, external: string): boolean {
return customElements.get(tag).observedAttributes.sort() === customElements.get(external).observedAttributes.sort();
}