@servicetitan/anvil2-codemods
Advanced tools
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.
Contributions are encouraged! See the Contributing docs for instructions.
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.
These are all of the transforms currently available that can be passed as the second argument of the CLI:
allbannerbody-textbuttonbutton-groupeyebrowheadlinelinktagtag-groupIf no transform is passed, a menu will appear to manually select transform(s) to run.
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.
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.
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.
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.
/*
* 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.
*/
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>
</>
);
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.
*/
In Anvil2, the el prop has been removed to promote consistency and better accessibility in our components.
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
*/
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.
*/
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.
Text component with variant="body" doesn't break the UI.className="d-i", className="fs-italic", className="fw-bold" from the Text component.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.
*/
In Anvil, a combination of fill and color props could be used to create many variations of buttons. These props included:
colorfillnegativeoutlineprimarytextIn 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.
appearance with your designerappearance propButton.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"
*/
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.
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.
*/
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.
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.
*/
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.
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.
*/
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.
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.
*/
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.
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
*/
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
fullWidthprop, which is used withequalWidth. More on that below.
flexGrow="1" prop on all children, or with custom CSSButtonGroup.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"
*/
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.
width: 100% to stylesgrow="1" on Flex if parent is also a flex container and has full-widthgridColumn or gridArea, if the parent is a grid containerFlexEyebrow.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.
*/
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.
Text component with variant="eyebrow" doesn't break the UI.className="d-i", className="fs-italic", className="fw-bold" from the Text component.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.
*/
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.
Text component with variant="headline" doesn't break the UI.className="d-i", className="fs-italic", className="fw-bold" from the Text component.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.
*/
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:
Headline had an el prop, we use that if it is h1, h2, h3, h4, h5, or h6.Headline had a size prop, we attempt to infer a correct value for el (small = h4, medium=h3, large=h2, xlarge=h1).el or size are invalid or unknown, we default to h3.Text component with variant="headline" has an appropriate heading level. Refer to MDN for more info on heading levels.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.
*/
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".
Link with a Button if it is meant to behave like a button.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.
*/
In Anvil2, links can no longer be disabled.
className, if necessaryLink.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.
*/
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.
className, if necessaryTag.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.
*/
In Anvil2, the subtle prop is no longer supported.
Chip component doesn't break the UI.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.
*/
In Anvil2, the color prop only supports color values such as HEX, RGB, HSL, and HSV.
Chip component doesn't break the UI.FAQs
Anvil 2 codemod scripts
We found that @servicetitan/anvil2-codemods demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Socket identified 80 fake candidates targeting engineering roles, including suspected North Korean operators, exposing the new reality of hiring as a security function.
Application Security
/Research
/Security News
Socket detected multiple compromised CrowdStrike npm packages, continuing the "Shai-Hulud" supply chain attack that has now impacted nearly 500 packages.
Research
/Security News
Malicious update to @ctrl/tinycolor on npm is part of a supply-chain attack hitting 40+ packages across maintainers