When you rely on custom components, sometimes you want to publish new versions and phase out previous versions. This document shows you how to version your custom components so that your team is using the most up-to-date iteration.
The following video shows two versions of a component in the Visual Editor and how, with minimal code edits you can deprecate one version in favor of another.
This document covers the following:
To version custom components, you should already be familiar with the following:
Always make new versions of custom components backward-compatible so that any content using a prior version of the component continues to work.
Builder uses the current version of the custom component when rendering your content because that is the version that exists on your site–even if the content was originally created with a prior version of the component.
For example, if the new version of the custom component has an additional input, make sure to handle the case where that input is undefined, since old content does not have a value for that input.
Importantly, even if you are deprecating a previous version of a component, keep that previous version registered with Builder so that any instances still in use continue to work properly.
Tip: If a defaultValue is passed to an input, Builder only applies that value to new content that uses the new component–it is not retroactive. For more information on defaultValue, refer to the defaultValue description in Input Types in Builder.
When naming your custom components, including when introducing new versions, be sure to give each component a unique name. You can use completely different names such as Our Header and Our New Header, or you can use a naming technique that uses version numbers in your code while maintaining the same name, unchanged, in the Visual Editor.
To manage names and versions of custom components, we recommend the following workflow:
- Optionally hide the previous version of the component to prevent its use.
- Give the component(s) a version number.
To hide and assign a version number to your components, follow the steps for your framework:
The following is a screenshot of a page with both versions of the HeadingComponent. The first version was added before it was deprecated by setting hideFromInsertMenu to true. and has the default value of "I'm version 1".
The second version replaced the first version with the same name in the Visual Editor, Heading, but the default value now says "I'm version 2".
The first version remains functional because it is still registered with Builder.
If the updates you want to make preclude backward compatibility, take the following steps:
- Create an entirely new component registered with a new name.
- Keep the previous version of the component registered with Builder so that existing content on your site using that component continues to function properly.
- Hide the old version of the component from the Builder editor so your team doesn't use the old version with newer content. To hide a component, use the
hideFromInsertMenuoption when registering the component, as in the following example code:
Tip: The content model backing the component does not update automatically.
To phase out custom components while ensuring that contents using those components still work as intended, use the hideFromInsertMenu option so your component is no longer visible in the Visual Editor.
Continuing to register a deprecated component with Builder means Builder can still use your component for older content while teammates use the newer version that's in the Insert tab.
For more detail, see the entry on hideFromInsertMenu in Registering Custom Components.
If you're iterating on your custom components, check out Input Types in Builder to get familiar with all the options available.
