@servicetitan/anvil2-codemods

Anvil2 Codemods

This package includes the source code for codemods created to make upgrading Anvil2 components and utilities easier.

Inspiration is from https://github.com/carlrip/codemod-react-ts.

Contributing

Contributions are encouraged! See the Contributing docs for instructions.

Using the codemods

To use this CLI tool to upgrade code from Anvil (@servicetitan/design-system) to Anvil2 (@servicetitan/anvil2), we recommend using npx to always use the latest version.

npx @servicetitan/anvil2-codemods@latest [path] [transforms] [options]

Using the --help option will give you the following description:

Arguments:
  path                    Files or directory to transform. Can be a glob like src/**.test.js. Can be relative path from current working directory or absolute path.
  transforms              One or many of the choices separated by comma (no space). Available choices are all,button. See
                          https://github.com/servicetitan/hammer/tree/master/packages/anvil2-codemods/README.md#transforms for more information.

Options:
  -f, --force             Bypass Git safety checks and forcibly run codemods
  --dry                   Dry run (no changes are made to files)
  --print                 Print transformed files
  --jscodeshift='<ARGS>'  Space separated jscodeshift CLI options. For example, --jscodeshift='--silent --run-in-band'. See https://jscodeshift.com/run/cli/#options for more information.
  -h, --help              Display this help

See the JSCodeshift docs for more info no available options to pass to --jscodeshift.

Transforms

These are all of the transforms currently available that can be passed as the second argument of the CLI:

• all
• button
• eyebrow

If no transform is passed, a menu will appear to manually select transform(s) to run.

Formatting after transforms

Due to the nature of how codemods are run, formatting using Prettier or similar tools is not done during the transform. You will likely need to reformat the page after running a codemod to match the project standards.

This is not something we plan to incorporate into the codemods tool, since there are many different tools, plugins, and configuration options for code formatting and linting.

Docs for missing transforms

There are some transforms that can't be automated with a codemod, usually because the Anvil version doesn't have an exact match in Anvil2. In such cases, a comment will be added with some details and a links to this page or to the Anvil2 documentation.

The rest of this page has instructions for individual cases that could not be auto-transformed.

Known issues (no automated message)

Removed import from Anvil that is used as a TypeScript Generic Parameter

If there is an import from @servicetitan/design-system that is only used on the page as a TypeScript generic parameter for a function (see example below), the import will be removed. This is related to a known issue in jscodeshift.

import { AnvilSelectMultipleProps } from "@servicetitan/design-system";

// ...other stuff...

/* 
  if this is the only AnvilSelectMultipleProps usage, the 
  import will be removed above
*/
const example = functionWithGenericParam<AnvilSelectMultipleProps>();

The solution is to manually add back the import that was removed. We will update the codemods once the issue is resolved on jscodeshift.

Generic messages

Component name changed and alias removed

Expand for details

---

/*
 * TODO (anvil2-codemods generated)
 * Component name changed and alias removed.
 * To continue using the alias name, manually adjust the import
 * statement and update the name here.
 */

Summary

Some components in Anvil map to new components in Anvil2 if they have a certain combination of props. For example, this Anvil Button:

<Button href="https://something.com">Open link</Button>

would change to a ButtonLink in Anvil2:

<ButtonLink href="https://something.com">Open link</ButtonLink>

Since there are other combinations of Button that do not result in a ButtonLink, there are some complexities involved with determining how an alias would work for a Button import that is used both as a regular Anvil2 Button and as a ButtonLink in the same page.

Because of this, we ask that certain aliases are manually adjusted after the codemod is done. Here's a full example, again using ButtonLink:

// before codemod
import { Button as AnvilButton } from "@servicetitan/design-system";

export const Component = () => (
  <>
    <AnvilButton>Regular Button</AnvilButton>
    <AnvilButton href="#">Button Link</AnvilButton>
  </>
);

// after codemod
import { Button as AnvilButton, ButtonLink } from "@servicetitan/anvil2";

export const Component = () => (
  <>
    <AnvilButton>Regular Button</AnvilButton>
    {/* ... codemods comment ... */}
    <ButtonLink href="#">Button Link</ButtonLink>
  </>
);

Next steps

1. Either manually update the alias for the the new component, or don't use an alias

---

Button

Button.appearance - Invalid combinations

Expand for details

---

/*
 * TODO (anvil2-codemods generated)
 * This combination of fill and color props is not supported
 * in Anvil2. Manually update the component to use a valid
 * appearance value.
 */

See Button appearance documentation

Summary

In Anvil, a combination of fill and color props could be used to create many variations of buttons. These props included:

• color
• fill
• negative
• outline
• primary
• text

In Anvil2, we've reduced the possible combinations and have a single appearance prop, which allows:

• "primary"
• "secondary"
• "danger"
• "danger-secondary"
• "ghost"

For any combination that doesn't easily translate from Anvil to Anvil2, manual intervention is required to set the new appearance. For example, a blue/outline button from Anvil could be either a "primary" or "secondary" button in Anvil2, depending on context.

Next steps

1. Verify the correct appearance with your designer
2. Remove any of the original Anvil props
3. Add the correct appearance prop

---

Button.el - No longer supported

Expand for details

---

/*
 * TODO (anvil2-codemods generated)
 * Button.el is no longer supported and has been removed from this component.
 * No action is required, but please verify this is the expected behavior.
 */

See Button documentation

Summary

In Anvil2, the el prop has been removed to promote consistency and better accessibility in our components.

Next steps

1. Verify the behavior and any custom styles of this Button is still correct

---

Button.full and Button.width - No longer supported

Expand for details

---

/*
 * TODO (anvil2-codemods generated)
 * The Button.width and Button.full props are no longer supported.
 * Action required. Either:
 *  - Add styles to a CSS class passed to Button.className
 *  - Use the Button.flexGrow or Button.flexBasis prop if
 *    parent is a Flex component or has display="flex"
 */

See Button documentation

Summary

In Anvil2, the Button.width and Button.full props are no longer supported. Custom styles must be added using one of the methods mentioned in the comment.

Next steps

1. Use CSS or Flex/Grid properties to achieve the desired button width

---

Button.icon - Verify SVG component

Expand for details

---

/*
 * TODO (anvil2-codemods generated)
 * The Anvil2 Button.icon prop should be an SVG component.
 * Make sure to update the custom Button.icon component value.
 */

See Button documentation

Summary

In Anvil2, the component passed to the Button.icon prop must be of Svg type:

type Svg = FC<SVGProps<SVGSVGElement>>;

*.svg files imported in projects that use svgo (default in ST MFEs and monolith) are converted to this type.

There may be no further action required, but if a TypeScript error crops up, the icon may need to be refactored to use the correct type, rather than the React.ReactElement type in Anvil.

Next steps

1. If a TypeScript error occurs, or the icon is not rendered, replace the current component with an SVG component.

---

Button.inactive - No longer supported

Expand for details

---

/*
 * TODO (anvil2-codemods generated)
 * The Button.inactive prop is no longer supported, and has been changed to Button.disabled in this component.
 * No action is required, but please verify this is the expected behavior with your designer.
 */

See Button documentation

Summary

In Anvil2, the inactive prop has been removed to promote consistency and better accessibility in our components. It is automatically replaced with disabled, which similarly prevents interactions, but also updates the UI and adds accessibility properties related to disabled elements.

Next steps

1. Verify that the button should be disabled

---

Button.xsmall and Button.size="xsmall" - No longer supported

Expand for details

---

/*
 * TODO (anvil2-codemods generated)
 * Button.size="xsmall" is no longer supported. This Button has been changed to small.
 * No action is required, but please verify this is the expected behavior with your designer.
 */

See Button size documentation

Summary

In Anvil2, xsmall buttons are no longer supported, either through the xsmall or size="xsmall" props. The button is automatically converted to a small button, but this may require some manual style adjustments if it breaks the UI.

Next steps

1. Verify that the new button size doesn't break the UI.
2. Make adjustments if needed.

---

Button Group

ButtonGroup.attached - Not supported in Flex

Expand for details

---

/*
 * ButtonGroup.attached is no longer supported and has been removed from this component.
 * Action required.
 *  - Work with designer to decide if the design should update
 *  - If not, remove gap="2" and add custom styles to Button children
 *    to achieve desired UI.
 */

See Flex documentation

Summary

Since the ButtonGroup no longer exists in Anvil2, and the Flex component does not have an attached prop, this behavior must be done custom. A designer should verify that this UI is still the expectation versus having a gap between the buttons.

Next steps

1. Work with designer to decide if the design should update
2. If not, remove gap="2" and add custom styles to Button children to achieve desired UI.

---

ButtonGroup.el - No longer supported

Expand for details

---

/*
 * TODO (anvil2-codemods generated)
 * ButtonGroup.el is no longer supported and has been removed from this component.
 * No action is required, but please verify this is the expected behavior.
 */

See Flex documentation

Summary

In Anvil2, the el prop has been removed to promote consistency and better accessibility in our components.

Next steps

1. Verify the behavior and any custom styles of this Flex is still correct

---

ButtonGroup.equalWidth - Not supported in Flex

Expand for details

---

/*
 * The ButtonGroup.equalWidth prop is no longer supported,
 * and at least one child could not be identified as a Button.
 * Action required. Either:
 *  - Add flexGrow="1" to all children if Anvil2 Buttons
 *  - Use styles in a CSS class on all children with flex-grow: 1
 */

See Flex documentation

Summary

Since the ButtonGroup no longer exists in Anvil2, and the Flex component does not have an equalWidth prop, this behavior must be done custom.

The codemod will automatically add flexGrow="1" to all Button components that are direct children of the new Flex component. For more complex cases, such as using a map function, the prop should be added manually.

This message will also appear if there are any JSX Element children that are not specifically named Button. If using an alias or passing through props to an Anvil2 Button, adding flexGrow="1" should work, otherwise you may need to add custom styles using a CSS class with flex-grow: 1.

Note: You will also need to add custom styling for the fullWidth prop, which is used with equalWidth. More on that below.

Next steps

1. Add CSS styles via the flexGrow="1" prop on all children, or with custom CSS

---

ButtonGroup.fullWidth - Not supported in Flex

Expand for details

---

/*
 * The ButtonGroup.fullWidth prop is no longer supported.
 * Action required. Either:
 *  - Add styles to a CSS class passed to Flex.className
 *  - Use the Flex.grow or Flex.basis prop if used within
 *    another Flex component or container with display="flex"
 */

See Flex documentation

Summary

Since the ButtonGroup no longer exists in Anvil2, and the Flex component does not have a fullWidth prop, this behavior must be done custom. This can be done a few ways, and depends on the parent element of the new Flex component.

Some options:

• Add width: 100% to styles
• Use grow="1" on Flex if parent is also a flex container and has full-width
• Use grid props, such as gridColumn or gridArea, if the parent is a grid container

Next steps

1. Add CSS styles to create a full-width button group using a Flex

---

Eyebrow

Eyebrow.inline, Eyebrow.el, Eyebrow.italic and Eyebrow.bold - No longer supported

Expand for details

---

/*
 * TODO (anvil2-codemods generated)
 * The inline, el, italic, and bold props are no longer supported, and have been removed from this component.
 * No action is required, but please verify this is the expected behavior.
 */

See Eyebrow documentation

Summary

In Anvil2, the inline, el, italic, and bold props are no longer supported. Eyebrows are now created using the Text component with the variant="eyebrow" prop.

Next steps

1. Verify that the new Text component with variant="eyebrow" doesn't break the UI.
2. Manually remove className="d-i", className="fs-italic", className="fw-bold" from the Text component.
3. Make adjustments if needed.

---