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?
Section titled “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
Section titled “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:
npx @cimpress-ui/codemod [options] <transform> <paths>
pnpm dlx @cimpress-ui/codemod [options] <transform> <paths>
yarn dlx @cimpress-ui/codemod [options] <transform> <paths>
To see all available options, run the command with the --help
flag:
npx @cimpress-ui/codemod --help
pnpm dlx @cimpress-ui/codemod --help
yarn dlx @cimpress-ui/codemod --help
Examples
Section titled “Examples”To run the v1
transform on all supported files in the current directory and all its subdirectories:
npx @cimpress-ui/codemod v1 .
pnpm dlx @cimpress-ui/codemod v1 .
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:
npx @cimpress-ui/codemod v1/demo src/components src/utils
pnpm dlx @cimpress-ui/codemod v1/demo src/components src/utils
yarn dlx @cimpress-ui/codemod v1/demo src/components src/utils
To run the v1
transform on src/components/MyCustomComponent.tsx
:
npx @cimpress-ui/codemod v1 src/components/MyCustomComponent.tsx
pnpm dlx @cimpress-ui/codemod v1 src/components/MyCustomComponent.tsx
yarn dlx @cimpress-ui/codemod v1 src/components/MyCustomComponent.tsx
Limitations
Section titled “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
Section titled “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 migratedconst 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
Section titled “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
Section titled “Migration reference”Component Library component | Cimpress UI equivalent(s) | Migration script |
---|---|---|
Accordion | 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 | 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 | N/A | |
Checkbox | v1/checkbox | |
DatePicker | N/A | |
Dropdown | v1/dropdown | |
FlexBox | Stack (for simple cases) | N/A |
Header | N/A | |
Label | v1/label | |
Modal | v1/modal | |
NavTab | v1/nav-tab | |
Pagination | v1/pagination | |
Radio | v1/radio | |
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 | v1/spinner | |
Table | N/A | |
ReactTableV6 | N/A | |
TabCard | v1/tab-card | |
Tag | v1/tag | |
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 |