<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5HGSQD2L" height="0" width="0" style="display:none;visibility:hidden" title="GTM"></iframe>

CLI

The SWAN Command Line Interface (CLI) is a unified tool for managing your SWAN package directly from your codebase using the command line.

Codemods

Overview

What is a codemod?

A codemod is a powerful 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+.


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.

A screenshot of the CLI terminal output, including results, disclaimers, and next steps.

An example of the CLI terminal output including results, disclaimers, and next steps.

An example of the CLI terminal output including results, disclaimers, and next steps.

A screenshot of the CLI terminal output, including results, 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.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