Skip to content

Migrating from Component Library

Migrating away from Component Library to a new solution can be a daunting task. To ease the burden on developers and speed up the migration process, Cimpress UI includes automated migration scripts.

You can use automated migration scripts in your project if:

  • you’re using Node >= 20
  • your project is currently using Component Library >= 16
  • your project uses an automated code formatting tool (like Prettier)

Migration scripts (transforms) are provided within the @cimpress-ui/codemod package. Transforms are named according to the following rules:

  • Transform name consists of a version identifier, and optionally a slash separator and a transform identifier.
  • Version identifier states the version of Cimpress UI that the transform migrates to.
  • Transform identifier describes what the transform is migrating.
  • Transforms that have names consisting of only a version identifier are group transforms - they execute all available transforms for that version.

See the @cimpress-ui/codemod readme for a list of available transforms.

To execute a transform, run the following command in a terminal:

Terminal window
npx @cimpress-ui/codemod [options] <transform> <paths>

To see all available options, run the command with the --help flag:

Terminal window
npx @cimpress-ui/codemod --help

To run the v1 transform on all supported files in the current directory and all its subdirectories:

Terminal window
npx @cimpress-ui/codemod v1 .

To run the v1/demo transform on all supported files in src/components, src/utils, and all their subdirectories:

Terminal window
npx @cimpress-ui/codemod v1/demo src/components src/utils

To run the v1 transform on src/components/MyCustomComponent.tsx:

Terminal window
npx @cimpress-ui/codemod v1 src/components/MyCustomComponent.tsx

While we try to provide complete migration scripts, in some cases it won’t be possible to fully migrate your code automatically. Make sure that your application builds and runs correctly after applying transforms.

Listed below are the most common cases which our migration scripts cannot handle:

  • prop values stored in variables

    // Example:
    // Button size "default" is renamed to "medium"
    // This will be migrated
    <Button size="default">My button</Button>;
    // This won't be migrated
    const buttonSize = 'default';
    <Button size={buttonSize}>My button</Button>;
  • event handler parameters

    // Example:
    // An event handler signature is changed from `({ isSelected }) => void` to `(isSelected) => void`
    // This won't be migrated
    <Checkbox onChange={onCheckboxChange}>My checkbox</Checkbox>
    <Checkbox onChange={({ isSelected }) => setIsSelected(isSelected)}>My checkbox</Checkbox>
  • changes that require knowledge about the structure of data

    // Example:
    // `Select` component now requires `selectedKey` prop of type `string`
    // instead of a `selectedOption` prop of type `object`
    // This won't be migrated, because we don't know the structure of `options`
    // and we don't know which property to use as the key
    <Select options={options} selectedOption={selectedOption} />
  • changes that require application-specific context

    // Example:
    // `Tag` components must now be wrapped with `TagGroup`
    // This won't be migrated, because we don't know which tags should be grouped together
    <Tag>Apple</Tag>
    <Tag>Banana</Tag>
    <Tag>Cherry</Tag>
    <Tag>Broccoli</Tag>
    <Tag>Carrot</Tag>

This tool may cause formatting loss when applying transforms. Make sure to run your project’s formatter on all transformed files.

Component Library
component
Cimpress UI equivalent(s)
Migration script
Accordion

Disclosure

v1/accordion
Alert

Alert (if rendered dynamically in response to user action)

Callout (for all other use cases)

v1/alert
(transforms to Callout only)
Breadcrumbs

Breadcrumbs

v1/breadcrumbs
Button

Button (if used with a label to perform an action)

IconButton (if used with an icon to perform an action)

LinkButton (if used with a label to perform navigation)

IconLinkButton (if used with an icon to perform navigation)

v1/button
Card

Card

N/A
Checkbox

Checkbox

v1/checkbox
DatePicker

DatePicker

N/A
Dropdown

Menu

v1/dropdown
FlexBox

Stack (for simple cases)

N/A
Header

AppHeader

N/A
Label

Badge

v1/label
Modal

ModalDialog

v1/modal
NavTab

LinkTabs

v1/nav-tab
Pagination

Pagination

v1/pagination
Radio

Radio

v1/radio
RadioGroup

RadioGroup

v1/radio-group
Select

Select (for single selection without filtering)

ComboBox (for single selection with filtering)

TagField (for multiple selection with filtering)

v1/select
Spinner

Spinner

v1/spinner
Table

Table

N/A
ReactTableV6

Table

N/A
TabCard

Tabs

v1/tab-card
Tag

Tag

v1/tag
TextArea

TextArea

v1/text-area
TextField

TextField (if used for non-numeric input)

NumberField (if used for numeric input)

v1/text-field
Tooltip

Tooltip (if shown on hover/focus, no interactive content)

Popover (if shown on press, interactive content)

v1/tooltip