Codemods | Tools

Overview

What is a codemod?

A codemod is a script that replaces the need for manually performing code changes. To make both major and minor upgrades easier, we offer codemods to automate as many of the manual code changes as possible.

When do I run codemods?

Technically, you are only required to make code changes when migrating to a major release, because a minor release will never introduce a breaking change that involves code changes.

However, we encourage you to run codemods during minor migrations, too! This is because we often deprecate features in minor releases to prepare for their removal in the next major release. By addressing these deprecations in your minor migrations, you’re setting yourself up for a much easier major migration later!

Which codemods do I run?

The codemods released with major versions are breaking - they can safely run only once. Run them ONLY when migrating from the previous major version.

The codemods released with minor versions are idempotent - they can be safely run more than once. Run them when your codebase is greater than or equal to its version, and less than the next major.

How to run codemods

Installation

To run the codemods, you will use the SWAN CLI, a unified tool for managing your SWAN package directly from your codebase using the command line.

The SWAN CLI is an NPX tool, so there is no need to install the package or its dependencies. However, it is required that you run the CLI using Node 18+.

npmyarn

npm install @vp/swan@latest
npx @vp/swan-cli@latest

npm install @vp/swan@latest
npx @vp/swan-cli@latest

yarn add @vp/swan@latest
yarn add @vp/swan-cli@latest

// Add a script in your package.json 
{
  "scripts": {
    "@vp/swan-cli" : "@vp/swan-cli"
  }
}

// Run yarn run codemod
yarn run @vp/swan-cli [commands] [options]

// After the codemods are done executing, remove the script added and the package from package.json
yarn remove @vp/swan-cli

yarn add @vp/swan@latest
yarn add @vp/swan-cli@latest

// Add a script in your package.json 
{
  "scripts": {
    "@vp/swan-cli" : "@vp/swan-cli"
  }
}

// Run yarn run codemod
yarn run @vp/swan-cli [commands] [options]

// After the codemods are done executing, remove the script added and the package from package.json
yarn remove @vp/swan-cli

Usage

You can simply run npx @vp/swan-cli@latest [command] [options] from the root of your codebase to invoke the latest and greatest version of the tool. Replace [command] and [options] with any of the flags below to customize your experience.

Commands

--run

Runs the codemod CLI, allowing you to select the directory to execute against, and which codemods to execute.

npx @vp/swan-cli@latest run

Options (optional):

--from

The minimum version, inclusive, to include in the preselection of codemods to execute. Codemods matching the from version will be run.

npx @vp/swan-cli@latest run --from=1.0.0

--to

The maximum version, exclusive, to include in the preselection of codemods to execute. Codemods matching the to version will not be run.

npx @vp/swan-cli@latest run --to=3.0.0

npx @vp/swan-cli@latest run --from=2.0.0 --to=3.0.0

--list

Lists the codemods without executing them.

npx @vp/swan-cli@latest run --list

Respects the `--from` and `--to` flag for displaying matching codemods.

npx @vp/swan-cli@latest run --list --from=2.0.0 --to=3.0.0

--verbose

When used with the `run` command, logs information about each file the transformations were run against.

npx @vp/swan-cli@latest run --verbose

When used with the `--list` option, logs all the transformations to be executed by the codemod.

npx @vp/swan-cli@latest run --list --verbose

--help, -h

When used with a command, displays help for that command.

npx @vp/swan-cli@latest run --help

When used on its own, lists available commands.

npx @vp/swan-cli@latest --help

Next steps

Once the codemods are done executing, you will see the results printed to your terminal along with some disclaimers and next steps.

Review the disclaimers

The codemods may not fix everything that is currently deprecated. For changes that cannot be automated with a codemod, you will find migration instructions in the next major release migration guide. For changes that can be partially automated with a codemod, you will find additional effort or review instructions listed in the "Disclaimers" section of the output. Note that disclaimers are logged for all codemods that were executed, even if they didn't transform any of your files.

Run your formatter

Be sure to run your own formatter (i.e. prettier, eslint). The codemod library we use will apply its own formatting against your transformed files, and they will be ugly 🙂

Verify the changes

Verify that the changes made by the codemods are accurate, extensive, and produced zero regressions by running your test suite, booting up your application, performing visual QA, and spot-checking the diff. Keep in mind that the codemod library cannot anticipate every use case, so look closely for things it may have missed!

List of codemods

Here is an up-to-date list of all available codemods and their disclaimers, grouped by their minimum compatible SWAN version.

3.24.0

Remove disabled prop from PaginationStep component
Remove disabled prop from TabHeader component

3.22.0

Replace icon-only Button component with IconButton component
- ⚠️ Update or verify the accessible text in the required tooltip prop (and optional aria-label if used). Refer to the Tooltip guidelines.
- ⚠️ If you are using unstyled, full-width, mini, or non-rounded Buttons, replace them manually.

3.16.0

Remove dialog prop from PopoverContent component

3.14.0

Replace ComboboxWithFloatingLabel, DropdownWithFloatingLabel, ListboxWithFloatingLabel and TextInputWithFloatingLabel (and their types, sub-components and their types) with InputWithFloatingLabel (and sub-component and type).
- ⚠️ Codemod will not include the fullWith prop if it already exists on the Dropdown or Listbox component with a different value than the prop on DropdownWithFloatingLabel or ListboxWithFloatingLabel. Please migrate it manually
Remove gridGuttersVariant prop from Carousel component.
Remove gutter prop from GridContainer component.

3.10.1

Rename visuallyHiddenLabel prop to accessibleText for AlertBoxDismissButton component
- ⚠️ This codemod renames visuallyHiddenLabel to accessibleText but retains the existing value, so if you used a React node, you'll need to update it to a string afterwards.
Rename visuallyHiddenLabel prop to accessibleText for ModalDialogCloseButton component
- ⚠️ This codemod renames visuallyHiddenLabel to accessibleText but retains the existing value, so if you used a React node, you'll need to update it to a string afterwards.
Rename visuallyHiddenLabel prop to accessibleText for ZoomControlsIn and ZoomControlsOut components
- ⚠️ This codemod renames visuallyHiddenLabel to accessibleText but retains the existing value, so if you used a React node, you'll need to update it to a string afterwards.
Rename visuallyHiddenLabel prop to accessibleText for ZoomControlsValue component
- ⚠️ This codemod renames visuallyHiddenLabel to accessibleText but retains the existing value, so if you used a React node, you'll need to update it to a string afterwards.

3.8.0

Remove skin prop from FormLabel component
Remove skin prop from StandardForm component

3.7.0

Move imageFocalPoint prop from Banner to BannerImage component
- ⚠️ Codemod will not run if the imageFocalPoint prop already exists on the BannerImage component with a different value than the prop on Banner. Please migrate it manually.

3.5.0

Remove style keys button, fieldSet, icon, pricing

3.3.0

Remove size prop from the Button component
Remove size prop from Callout component
Remove size prop from Dropdown component
Remove size prop from Listbox component
Remove size prop from TextInput component
Remove size prop from ToggleSwitch component
Rename iconType prop values for Icon component (closeLarge -> close, closeSmall -> close, toggleOff -> cross, plusRounded -> add, satisfaction -> guaranteedSatisfaction, caretRight -> chevronRight, login -> arrowRight, uploadYourArtwork -> upload, searchLarge -> search, clock -> orderHistory, myProjects_1 -> myProjects, polish -> sparkle, deleteStudio -> delete, playRounded -> play, chatReview -> liveChat, phoneCall -> phone, help -> phone, checkRoundedEdges -> check, checkRoundedEdgesMini -> check, heartEmpty -> heart, heartFilled -> heart, starEmpty -> star, starFilled -> star)
Rename size prop values for Icon component (10p -> 16p, 28p -> standard, 32p -> standard, 40p -> standard, 48p -> standard, 60p -> standard)
Rename swan-icon-size-1em, swan-icon-size-1rem classes to swan-icon-size-standard
Rename size prop values for Spinner component (mini -> standard, tiny -> standard)
Remove wrapHeaders prop from Tabs component
Rename skin prop values for Callout component (foil -> info, new/announcement -> accent, discount -> promo, standard -> info)
Remove border prop from Callout component
Replace variant="overlay" prop with emphasis="low" and remove variant prop from Callout component
Rename skin prop value from line to standard for Dropdown component
Remove width prop from AlertBox component
Rename skin prop values for AlertBox component (standard -> info, positive -> success)
Remove textHorizontalAlignOnExtraSmall prop from Banner component
Rename iconType prop value from email to mail for Icon component

3.0.0

Migrate margin*/m*, padding*/p* prop values (1 -> 2, 2 -> 3, 3 -> 4, 4 -> 5, 5 -> 6, 6 -> 7, 13 -> 12)
- ⚠️ This codemod can only be run ONCE to migrate space props from SWAN v2 to v3.
Migrate fontFamily prop values (graphik -> primary, secondary -> primary, special -> secondary)
Migrate import paths for mixins to @vp/swan/mixins/*
Remove skin prop from ThumbnailsHero component
Rename prop names for Typography component (align -> textAlign, weight -> fontWeight)
Rename constants and import paths for tokens (dtcgTokens -> tokens)
Remove style keys (controlIcon, detailsBanner, embeddedTextHero, promoBar, secondaryTile, standardBanner, standardHero, combobox, menu, legacy*)
Remove skin prop from Table component
Rename type StyleSpacing0to13 to StyleSpaceWithAuto

2.22.0

Rename fontWeight prop value from bolder to boldMigrate fontSize prop values (-1-6, m*, x*, xm* -> xsmall-x4large)Migrate color design tokens to the SWAN v3 token architecture
- ⚠️ This codemod does not work on bracket object notation or with destructured values
- ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
- ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
Migrate font design tokens to the SWAN v3 token architecture
- ⚠️ This codemod does not work on bracket object notation or with destructured values
- ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
- ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
Migrate component design tokens to the SWAN v3 token architecture
- ⚠️ This codemod does not work on bracket object notation or with destructured values
- ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
- ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
Migrate element design tokens to the SWAN v3 token architecture
- ⚠️ This codemod does not work on bracket object notation or with destructured values
- ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
- ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
Migrate size design tokens to the SWAN v3 token architecture
- ⚠️ This codemod does not work on bracket object notation or with destructured values
- ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
- ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
Migrate state design tokens (selected/disabled) to the SWAN v3 token architecture
- ⚠️ This codemod does not work on bracket object notation or with destructured values
- ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
- ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
Migrate base design tokens to the SWAN v3 token architecture
- ⚠️ This codemod does not work on bracket object notation or with destructured values
- ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
- ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
Migrate shadow design tokens to the SWAN v3 token architecture
- ⚠️ This codemod does not work on bracket object notation or with destructured values
- ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
- ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
Migrate spacing design tokens to the SWAN v3 token architecture
- ⚠️ This codemod does not work on bracket object notation or with destructured values
- ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
- ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
Migrate media query (mq) design tokens to the SWAN v3 token architecture
- ⚠️ This codemod does not work on bracket object notation or with destructured values
- ⚠️ This codemod will not change tokens used as an SCSS mixin or SCSS function
- ⚠️ This codemod will only replace tokens with a direct replacement. For all other tokens, refer to https://vista.design/swan/foundations/all-tokens/ and work with your designer to find a suitable replacement.
Rename textColor prop values (alert -> error, black, black-800 -> standard, dark-grey, dark-gray, grey-700, gray-700 -> subtle)
Remove starsToShow prop from RatingsStars component

2.21.0

Rename lightMode prop value and CSS class to standardMode
Replace backgroundColor="loading-shimmer" prop with loadingShimmer
Migrate backgroundColor/bgc prop values (discount -> promo, grey/gray-*, platinum, light-grey/gray -> strong, black-900 -> black, white-900/white -> standard, dark-blue, atlantic, kingfisher -> accent)

2.20.0

Migrate constant GLOBAL_FONT to new color token
Migrate SEMANTIC_COLORS properties to new color tokens
- ⚠️ If you have used SEMANTIC_COLORS.selected, you may need to change SwanSemColorBgSelected to SwanSemColorBorderSelected.
Migrate SOURCE_COLORS properties to new color tokens

2.17.0

Remove contentWidth prop from ThumbnailsHero component
Remove imageShadow prop from StandardTile component
Remove skin="brand-blue" prop from Icon component
Remove size prop from FormError, FormHelper, FormLabel components
Rename skin prop value from accent to primary for Button component
Rename component from ButtonSuperBreak to br
Replace component Icon* with <Icon iconType="*">
Remove skin="peek" prop from Accordion component
Replace component StandardSection with Box
Rename skin prop value from comparison to dividers for Table component
Rename skin prop value from simple to dividers for Table component

2.13.0

Remove borderless prop from Dropdown component
Remove fixedWidthHeaders, size props from Tabs component
Remove fullWidthHeader prop from Tabs component
Remove skin="link" prop from Listbox, BasicListbox componentsRemove rich, richLastAlign props from CollapsibleSummary component
Remove size="large" prop from Accordion component
Remove size="mega" prop from TextInput component
Remove size="super" prop from Callout component
Rename 'progressIndicator prop value from fraction to none for Carousel component
Rename prop values and components for Icon component (shoppingBag_x -> shoppingBag_0, IconShoppingBag_x -> IconShoppingBag_0, redLegacy -> redo, IconRedoLegacy -> IconRedo, undoLegacy -> undo, IconUndoLegacy -> Undo)
Rename srOnly prop to visuallyHiddenRename skin prop value from gallery to product for StandardTile component
Migrate textSize prop to fontSize (1 -> x4, 2 -> x3, 3 -> x2, 4 -> x1, 5 -> x, 6 -> xm1, 7 -> xm2)
Rename skin prop value from standard to under for ThumbnailsHero component

2.5.0

Remove rounded prop from Dropdown component
Rename textColor prop values (alert -> error, black -> black-800, dark-grey/gray -> grey-700)
Rename textColor prop value from black-900 to black-800

2.0.0

Rename color constants (colors -> SEMANTIC_COLORS, sourceColors -> SOURCE_COLORS)
Rename constant from globalFont to GLOBAL_FONT
Rename component from LegacyModalDialog to ModalDialog
- ⚠️ Visual QA recommended, especially if you had any snowflakes on your LegacyModalDialog.
- ⚠️ If you have added a backgroundColor or bgc prop onto LegacyModalDialogContent, you will need to manually move that prop to ModalDialog now.
Rename component from LegacyPopover to Popover
- ⚠️ Visual QA recommended, especially if you had any snowflakes on your LegacyPopover.
Rename marketing constants (marketingBackgroundTokenMapping -> MARKETING_BACKGROUNDS, marketingBackgroundColors -> MARKETING_COLORS)
Rename component from Paginator to Pagination
Rename component from PipeDivider to PipeSeparator
Rename screen class constants (screenClasses -> SCREEN_CLASSES, screenClassMax/MinWidths -> SCREEN_CLASS_MAX/MIN_WIDTHS)
Rename component from SecondaryTileBadges to SecondaryTileCallouts
Rename spacing constants (spacing -> SPACING, spacingPx -> SPACING_PX)
Rename component from TableTextSecondLine to TableTextNewLineRename textAlign prop to textHorizontalAlign
Rename component from TextButton to Button
Rename widthVariant prop to widthRemove skin prop from Collapsible component
Rename allCaps prop to textAllCaps
Replace component BasicPreloader with Spinner
- ⚠️ Add the new "spinner" style key
- ⚠️ Add the required ARIA attributes for a11y support, you can find guidelines in the docs: https://vista.design/swan/components/spinner/?tab=Usage#Accessibility
- ⚠️ If you are using Preloader (instead of BasicPreloader), replace it manually
Rename cardDividers prop to dividers for GridContainer component
Rename sizeVariant prop to size
Rename visuallyHiddenText prop to accessibleText
Replace component ControlIcon with Icon
Replace minimal prop with skin="minimal" in List, Ul components