Skip to content
Cimpress UI

Codemods

To ease the burden on developers and speed up the migration process, Cimpress UI provides 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

Examples

Section titled “Examples”

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

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 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

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.