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.

Is this for me?

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)

Using automated migration scripts

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:

npm

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

pnpm

pnpm dlx @cimpress-ui/codemod [options] <transform> <paths>

Yarn

yarn dlx @cimpress-ui/codemod [options] <transform> <paths>

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

npm

npx @cimpress-ui/codemod --help

pnpm

pnpm dlx @cimpress-ui/codemod --help

Yarn

yarn dlx @cimpress-ui/codemod --help

Examples

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

npm

npx @cimpress-ui/codemod v1 .

pnpm

pnpm dlx @cimpress-ui/codemod v1 .

Yarn

yarn dlx @cimpress-ui/codemod v1 .

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

npm

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

pnpm

pnpm dlx @cimpress-ui/codemod v1/demo src/components src/utils

Yarn

yarn dlx @cimpress-ui/codemod v1/demo src/components src/utils

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

npm

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

pnpm

pnpm dlx @cimpress-ui/codemod v1 src/components/MyCustomComponent.tsx

Yarn

yarn dlx @cimpress-ui/codemod v1 src/components/MyCustomComponent.tsx

Limitations

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.

Common unsupported scenarios

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>

Code formatting

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

Migration reference

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

Toggle sort order of column: