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.

• Anvil2 Codemods
  • Contributing
  • Using the codemods
    • Transforms
    • Formatting after transforms
  • Docs for missing transforms
    • Known issues (no automated message)
      • Removed import from Anvil that is used as a TypeScript Generic Parameter
      • Anvil (1) Text components might need to be ran multiple times
    • Generic messages
      • Component name changed and alias removed
        • Summary
        • Next steps
      • Component.el - No longer supported
        • Summary
        • Next steps
    • Banner
      • Banner.icon - No longer supported
    • BodyText
      • BodyText.inline, BodyText.italic and BodyText.bold - No longer supported
        • Summary
        • Next steps
    • Button
      • Button.appearance - Invalid combinations
        • Summary
        • Next steps
      • Button.full and Button.width - No longer supported
        • Summary
        • Next steps
      • Button.icon - Verify SVG component
        • Summary
        • Next steps
      • Button.inactive - No longer supported
        • Summary
        • Next steps
      • Button.xsmall and Button.size="xsmall" - No longer supported
        • Summary
        • Next steps
    • Button Group
      • ButtonGroup.attached - Not supported in Flex
        • Summary
        • Next steps
      • ButtonGroup.equalWidth - Not supported in Flex
        • Summary
        • Next steps
      • ButtonGroup.fullWidth - Not supported in Flex
        • Summary
        • Some options:
        • Next steps
    • Eyebrow
      • Eyebrow.inline, Eyebrow.italic and Eyebrow.bold - No longer supported
        • Summary
        • Next steps
    • Headline
      • Headline.inline, Headline.italic, Headline.subdued and Headline.bold - No longer supported
        • Summary
        • Next steps
      • Headline.el - Now required
        • Summary
        • Next steps
    • Link
      • Link as a button (no href) - No longer supported
        • Summary
        • Next steps
      • Link.disabled - No longer supported
        • Summary
        • Next steps
      • Link.negative - No longer supported
        • Summary
        • Next steps
    • Stack
      • Stack.Item - Converted to div
        • Summary
        • Next steps
      • Stack.vertical - Requires manual conversion
        • Summary
        • Next steps
      • Stack.nowrap - Removed
        • Summary
        • Next steps
      • Stack.alignment - Requires manual conversion
        • Summary
        • Next steps
      • Stack.distribution - Requires manual conversion
        • Summary
        • Next steps
      • Stack.distribution - Unsupported values
        • Summary
        • Next steps
      • Stack spread props - Requires manual verification
        • Summary
        • Next steps
        • Example
    • Tag
      • Tag.subtle - No longer supported
        • Summary
        • Next steps
      • Tag.color - No longer supported
        • Summary
        • Next steps

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/main/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
• banner
• body-text
• button
• button-group
• eyebrow
• headline
• link
• stack
• tag
• tag-group

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.

Anvil (1) Text components might need to be ran multiple times

There is an issue that occurs when multiple Anvil (1) components are mapped to a single Anvil2 component, where only one component is transformed at a time.

For example, if both a <BodyText /> and <Headline /> component are used, only one will be transformed the first time you run the code, and the other will remain as-is. This should be resolved by running the transform again.

Generic messages

Component name changed and alias removed

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

Component.el - No longer supported

/*
 * TODO (anvil2-codemods generated)
 * Component.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 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 component is still correct

Banner

Banner.icon - No longer supported

/*
 * The icon prop is no longer supported, and has been removed from this component.
 * Icons will always be displayed on the left side of the Anvil2 Alert.
 * No action is required, but please verify this is the expected behavior.
 * https://github.com/servicetitan/hammer/tree/main/packages/anvil2-codemods#bannericon---no-longer-supported
 */

See Alert documentation

BodyText

BodyText.inline, BodyText.italic and BodyText.bold - No longer supported

/*
 * TODO (anvil2-codemods generated)
 * The inline, 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 Body Text documentation

Summary

In Anvil2, the inline, italic, and bold props are no longer supported. Body text is now created using the Text component with the variant="body" prop.

Next steps

1. Verify that the new Text component with variant="body" 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.

Button

Button.appearance - Invalid combinations

/*
 * 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.full and Button.width - No longer supported

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

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

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

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

/*
 * 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.equalWidth - Not supported in Flex

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

/*
 * 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.italic and Eyebrow.bold - No longer supported

/*
 * TODO (anvil2-codemods generated)
 * The inline, 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, 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.

Headline

Headline.inline, Headline.italic, Headline.subdued and Headline.bold - No longer supported

/*
 * TODO (anvil2-codemods generated)
 * The inline, italic, subdued, 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 Headline documentation

Summary

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

Next steps

1. Verify that the new Text component with variant="headline" 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.

Headline.el - Now required

/*
 * TODO (anvil2-codemods generated)
 * The el prop is required and has been added to this component based on the previous size prop (${size} = ${el}).
 * Please verify this is the expected semantic element.
 */

// OR

/*
 * TODO (anvil2-codemods generated)
 * The el prop is required and has been added to this component (default "h3").
 * Please verify this is the expected semantic element.
 */

// OR

/*
 * TODO (anvil2-codemods generated)
 * The el prop is required and should be one of: h1, h2, h3, h4, h5, h6.
 * The el prop has been updated from to "h3" for this component.
 */

See Headline documentation

Summary

In Anvil2, the el prop is required on Text when variant="headline". A valid el is important for semantics and accessibility. We apply an imperfect system to set this value for you:

• If your A1 Headline had an el prop, we use that if it is h1, h2, h3, h4, h5, or h6.
• If your A1 Headline had a size prop, we attempt to infer a correct value for el (small = h4, medium=h3, large=h2, xlarge=h1).
• If the values of el or size are invalid or unknown, we default to h3.

Next steps

1. Verify that the new Text component with variant="headline" has an appropriate heading level. Refer to MDN for more info on heading levels.
2. Make adjustments if needed.

Link

Link as a button (no href) - No longer supported

/*
 * TODO (anvil2-codemods generated)
 * Link should not be used as a button for proper screen reader announcements.
 * Use a Button with appearance="ghost" instead.
 * Please verify this is the expected behavior with your designer.
 */

See Link documentation

Summary

In Anvil2, the href attribute should always be used with a Link. It should not be used as a link-styled button element. The next best option would be to use a Button with appearance="ghost".

Next steps

1. Replace the Link with a Button if it is meant to behave like a button.
2. Or, add the href attribute.

Link.disabled - No longer supported

/*
 * TODO (anvil2-codemods generated)
 * Link.disabled is no longer supported and has been removed
 * from this component. Please verify this is the expected
 * behavior with your designer.
 */

See Link variations documentation

Summary

In Anvil2, links can no longer be disabled.

Next steps

1. Verify if any other changes should be made with your designer
2. Add custom styles using className, if necessary

Link.negative - No longer supported

/*
 * TODO (anvil2-codemods generated)
 * Link.negative is no longer supported and has been removed
 * from this component. Please verify this is the expected
 * behavior with your designer.
 */

See Link variations documentation

Summary

In Anvil2, links can no longer be negative in order to conform to accessibility best practices. Using only color to represent meaning is problematic for colorblind users, and red text generally has worse contrast ratios with certain background colors.

Next steps

1. Verify if any other changes should be made with your designer
2. Add custom styles using className, if necessary

Stack

Stack.Item - Converted to div

/*
 * TODO (anvil2-codemods generated)
 * Stack.Item has been converted to a div with inline styles.
 * https://github.com/servicetitan/hammer/tree/main/packages/anvil2-codemods#stackitem---converted-to-div
 */

Summary

The Stack.Item subcomponent has been replaced with a regular div element. The codemod will automatically convert Stack.Item-specific props to inline styles:

• fill → style={{ flex: "1 1 auto" }}
• basis → style={{ flexBasis: ... }}
• grow → style={{ flexGrow: ... }}
• shrink → style={{ flexShrink: ... }}
• order → style={{ order: ... }}
• alignSelf → kept as a prop

Next steps

1. Verify the converted styles work as expected
2. If there's an existing style prop, manually merge the generated styles

Stack.vertical - Requires manual conversion

/*
 * TODO (anvil2-codemods generated)
 * The vertical prop has been removed. Please manually update this to use
 * direction="column" if vertical is true, or direction="row" (default) if false.
 * https://github.com/servicetitan/hammer/tree/main/packages/anvil2-codemods#stackvertical---requires-manual-conversion
 */

Summary

If the vertical prop uses a dynamic expression (not a boolean literal), the codemod cannot automatically convert it and will add a comment.

Next steps

1. Manually update the prop to use direction="column" or direction="row"
2. Remove the vertical prop

Stack.nowrap - Removed

/*
 * TODO (anvil2-codemods generated)
 * The nowrap prop has been removed. Flex uses the wrap prop instead.
 * If you need nowrap behavior, add wrap="nowrap" to the Flex component.
 * https://github.com/servicetitan/hammer/tree/main/packages/anvil2-codemods#stacknowrap---removed
 */

Summary

The nowrap prop has been removed. If you need to prevent wrapping, use wrap="nowrap" on the Flex component instead.

Next steps

1. If nowrap behavior is needed, add wrap="nowrap" to the Flex component
2. Otherwise, no action is required

Stack.alignment - Requires manual conversion

/*
 * TODO (anvil2-codemods generated)
 * The alignment prop has been converted to alignItems. Please manually update
 * the value mapping: leading → flex-start, trailing → flex-end, center → center,
 * fill → stretch, baseline → baseline.
 * https://github.com/servicetitan/hammer/tree/main/packages/anvil2-codemods#stackalignment---requires-manual-conversion
 */

Summary

If the alignment prop uses a dynamic expression, the codemod cannot automatically convert it.

Next steps

1. Manually convert the value using the mapping above
2. Rename the prop to alignItems

Stack.distribution - Requires manual conversion

/*
 * TODO (anvil2-codemods generated)
 * The distribution prop has been converted to justifyContent. Please manually update
 * the value mapping: leading → flex-start, trailing → flex-end, center → center,
 * equalSpacing → space-between. Note: fill and fillEvenly are not supported.
 * https://github.com/servicetitan/hammer/tree/main/packages/anvil2-codemods#stackdistribution---requires-manual-conversion
 */

Summary

If the distribution prop uses a dynamic expression, the codemod cannot automatically convert it.

Next steps

1. Manually convert the value using the mapping above
2. Rename the prop to justifyContent
3. For fill and fillEvenly values, choose an appropriate alternative

Stack.distribution - Unsupported values

/*
 * TODO (anvil2-codemods generated)
 * The distribution="fill" value is not supported in Flex.
 * Please manually update to use an appropriate justifyContent value.
 * Available values: flex-start, flex-end, center, space-between, space-around, space-evenly.
 * https://github.com/servicetitan/hammer/tree/main/packages/anvil2-codemods#stackdistribution---unsupported-values
 */

Summary

The distribution values fill and fillEvenly are not supported in the Flex component.

Next steps

1. Choose an appropriate justifyContent value for your use case
2. Update the component accordingly

Stack spread props - Requires manual verification

/*
 * TODO (anvil2-codemods generated)
 * Unable to statically analyze spread props. Please verify all spread props
 * are valid for the Flex component.
 * https://github.com/servicetitan/hammer/tree/main/packages/anvil2-codemods#stack-spread-props
 */

Summary

When a Stack component uses spread props (e.g., <Stack {...props}>), the codemod cannot statically analyze what props are being spread. You'll need to manually verify that all spread props are valid for the Flex component.

Next steps

1. Review the spread props object and verify all props are compatible with Flex
2. Check for and convert any deprecated Stack props:
   • vertical → direction
   • nowrap → remove (use wrap="nowrap" if needed)
   • alignment → alignItems
   • distribution → justifyContent
   • spacing → gap

Example

Before:

const stackProps = {
  vertical: true,
  spacing: 2,
  alignment: "center",
};

<Stack {...stackProps}>Content</Stack>;

After codemod:

{
  /* Warning comment about spread props */
}
<Flex {...stackProps}>Content</Flex>;

Manually fix to:

const flexProps = {
  direction: "column",
  gap: "4",
  alignItems: "center",
};

<Flex {...flexProps}>Content</Flex>;

Tag

Tag.subtle - No longer supported

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

See Chip documentation

Summary

In Anvil2, the subtle prop is no longer supported.

Next steps

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

Tag.color - No longer supported

/*
 * TODO (anvil2-codemods generated)
 * The color prop is no longer supports the info, warning, critical, success, inactive, and inverse values, and has been removed from this component.
 * No action is required, but please verify this is the expected behavior.
 */

See Chip documentation

Summary

In Anvil2, the color prop only supports color values such as HEX, RGB, HSL, and HSV.

Next steps

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