Codemods

What are Codemods?

Codemods are scripts that help automate large-scale codebase refactors. They are particularly useful when updating code to align with new library versions or when making sweeping changes across multiple files. Chroma provides a set of codemods to assist developers in migrating their codebases efficiently and consistently.

Why use Codemods?

Codemods save time and reduce the risk of human error during refactoring tasks. By automating repetitive changes, developers can ensure consistency across their codebase while freeing up time to focus on more complex development tasks. Additionally, codemods can help maintain code quality by adhering to best practices and standards defined by the Chroma design system.

When to use Codemods?

Codemods should be used when you need to make bulk changes to your codebase that follow a specific pattern or rule. This could include updating component props, renaming variables, or restructuring code to align with new design system guidelines. Before running a codemod, it's essential to review the changes it will make and ensure you have a backup of your codebase in case you need to revert any changes.

How to use Codemods?

Chroma's codemods are built using jscodeshift. To use a codemod, follow these steps:

Install jscodeshift as a global package:

npm install -g jscodeshift or yarn global add jscodeshift

Run the Codemod: Use the jscodeshift CLI to run the desired codemod on your codebase via the command line. For example:

yarn jscodeshift -t node_modules/@iag/chroma-react-ui-utils.codemods/transforms/chroma-codemod-example.js src/

Review Changes: After running the codemod, review the changes it made to your codebase. Make sure to test your application thoroughly to ensure everything works as expected.

Available Codemods

The following codemods are designed to help you update your chroma-react components efficiently:

values-to-options

This codemod converts values props to options props in the following Chroma components:

• Autocomplete
• Checkbox
• Radio
• RadioBlock
• SegmentedControl
• Select

To run this codemod, use the following command:

 yarn jscodeshift -t node_modules/@iag/chroma-react-ui-utils.codemods/transforms/values-to-options.js src/

Example transform:

// Before
<Autocomplete
  values={[{ label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }]}
/>
// After
<Autocomplete
  options={[{ label: 'Option 1', value: '1' }, { label: 'Option 2', value: '2' }]}
/>

button-boolean-to-variant

This codemod updates Button components by replacing boolean props with the appropriate variant prop values.

To run this codemod, use the following command:

yarn jscodeshift -t node_modules/@iag/chroma-react-ui-utils.codemods/transforms/button-boolean-to-variant.js src/

Example transform:

// Before
<Button primary>Click Me</Button>
<Button secondary>Click Me</Button>
<Button tertiary>Click Me</Button>

// After
<Button variant="primary">Click Me</Button>
<Button variant="secondary">Click Me</Button>
<Button variant="tertiary">Click Me</Button>

modal-migration

This codemod updates Modal components to use the new MUI Modal component props. The following changes are made:

The following props are removed:

- appElement
- brand
- title
- style
- onHide

The following props are converted to new props:

- isOpen -> open
- labelledBy -> aria-labelledby
- describedBy -> aria-describedby

Because the title prop has been removed you will need to manually add a heading element inside the Modal component for accessibility that has an id attribute matching the aria-labelledby prop.

To run this codemod, use the following command:

yarn jscodeshift -t node_modules/@iag/chroma-react-ui-utils.codemods/transforms/modal-migration.js src/

Example transform:

// Before
<Modal
  appElement={document.getElementById("app")}
  title="How is my premium calculated roughly?"
  brand="chroma"
  shouldCloseOnOverlayClick
  onClose={handleClose}
  onHide={handleHide}
  onShow={handleShow}
  isOpen={isOpen}
  labelledby="modal-title"
  describedby="modal-description"
>
  <h2 id="modal-title">Modal Title</h2>
  <p id="modal-description">Modal Content</p>
</Modal>;

// After
<Modal
  shouldCloseOnOverlayClick
  onClose={handleClose}
  onShow={handleShow}
  open={isOpen}
  aria-labelledby="modal-title"
  aria-describedby="modal-description">
  <h2 id="modal-title">Modal Title</h2>
  <p id="modal-description">Modal Content</p>
</Modal>;

tab-migration

This codemod updates Tab from the old version to the new version by making the following changes:

• Converts Tab components to use TabItem components as children instead of using props.
• Moves the component prop from Tab to each individual TabItem.

To run this codemod, use the following command:

yarn jscodeshift -t node_modules/@iag/chroma-react-ui-utils.codemods/transforms/tab-migration.js src/

Example transform:

// Before
<Tab>
  <TabItem
    tab={{
      component: <>Tab 1</>,
      name: "tab1",
    }}
    content={{
      component: <p>Tab one content</p>,
    }}
  />
  <TabItem
    id="tabItem2"
    tab={{
      component: "Tab 2",
      name: "tab2",
    }}
    content={{
      component: <p>Tab two content</p>,
    }}
  />
</Tab>

// After
<Tab>
  <TabItem
    label={<>Tab 1</>}
  >
    <p>Tab one content</p>
  </TabItem>
  <TabItem
    label={"Tab 2"}
  >
    <p>Tab two content</p>
  </TabItem>
</Tab>