Custom component versioning

An application that uses your custom component is dependent upon the component’s definition (e.g. the component’s properties). If you change parts of your custom component's definition, the application that uses it may have compatibility issues with the new version (e.g., rename or delete a property, change its type, etc.).
To version your component to limit compatibility issues, do one of the following:
​Create a backward-compatible update​
​Deprecate the old component​
Create a backward-compatible update
To minimize compatibility issues with the new version of your component, create a backward-compatible update.
This example shows a backward-compatible update for the Simple Button component from the Create a component page:
Initial component:
  export default registerComponent('my-ui-component', {
    component: SimpleButton,
    name: 'Simple Button',
    props: [
      {
        name: 'label',
        type: PropType.String,
        value: 'My Label',
      },
      {
        name: 'onClick',
        type: PropType.Event,
      },
    ],
  });
Updated component:
export default registerComponent('my-ui-component', {
  component: SimpleButton,
  name: 'Simple Button',
  props: [
    {
      name: 'label',
      type: PropType.String,
      value: 'My Label',
    },
     {
      name: 'onClick',
      type: PropType.Event,
      // Added arguments for the `onClick` event. Previous versions will not include the counter.
      arguments: [
        {
          name: 'counter',
          type: PropType.Number,
        }
      ],
      onEmit({ args, emit }) {
        // The `newCounter` is passed as the first argument of `props.onClick`
        const newCounter = args[0];
        // Specify the event name and arguments to emit
        emit('onClick', { counter: newCounter });
      }
    },
  ],
  render({ props, className }) {
    const [counter, setCounter] = React.useState(0);
​
    const onClick = () => {
      const newCounter = counter + 1;
      setCounter(newCounter);
      props.onClick(newCounter);
    }
​
    return (
      <SimpleButton
        className={className}
        label={props.label}
        onClick={onClick}
      />
    )
  }
});
Deprecate the old component
When backward-compatibility is not possible or complex, deprecate the old version and start a new one from scratch.
Note: Deprecated component versions are not available in the catalog, but keeping them in your component library enables existing instances to continue functioning.
The example below demonstrates how to deprecate your old component and build a new one from scratch.
Deprecate the old component:
// components/MyComponent/index.ts
​
export default registerComponent('my-ui-component', {
  // Deprecate the component 
  deprecated: true,
  component: SimpleButton,
  name: 'Simple Button',
  props: [
    {
      name: 'label',
      type: PropType.String,
      value: 'My Label',
    },
    {
      name: 'onClick',
      type: PropType.Event,
    },
  ],
});
Create new component version from scratch:
// components/MyComponentV2/index.ts
​
export default registerComponent('my-ui-component-v2', {
  component: SimpleButton,
  name: 'Simple Button',
  props: [
    {
      name: 'label',
      type: PropType.String,
      value: 'My Label',
    },
     {
      name: 'onClick',
      type: PropType.Event,
      arguments: [
        {
          name: 'counter',
          type: PropType.Number,
        }
      ],
      onEmit({ args, emit }) {
        const newCounter = args[0];
        emit('onClick', { counter: newCounter });
      }
    },
  ],
  render({ props, className }) {
    const [counter, setCounter] = React.useState(0);
​
    const onClick = () => {
      const newCounter = counter + 1;
      setCounter(newCounter);
      props.onClick(newCounter);
    }
​
    return (
      <SimpleButton
        className={className}
        label={props.label}
        onClick={onClick}
      />
    )
  }
});
Last modified 1mo ago