Learn how to ease migration to new versions of Racine using codemods.

About codemods

We recognize that upgrading dependencies can be a chore, so we release codemods to facilitate upgrades for our users whenever possible, especially for breaking changes. Codemods are scripts that automatically apply updates to your code. They are especially useful for automating straightforward but tedious updates, such as renaming components or updating import paths.

Racine includes a developer tool called racine-codemod that helps you run our codemods. Our tool is powered by jscodeshift, a JavaScript codemod toolkit maintained by Meta. jscodeshift is a developer dependency of Racine, so it will be installed for your use as a developer but not shipped to your users.

Please note that codemods cannot handle 100% of changes needed to accommodate every breaking change. You should always look over codemod results and test your app.

Running codemods

In a repository where @sproutsocial/racine is already installed, you can use the following commands to run and view documentation for codemods:

Arguments

You can pass any jscodeshift command line arguments to racine-codemod, and they will be passed through to jscodeshift.

Additionally, individual codemods may accept arguments specific to that codemod. You can view a description of those arguments and a full usage example by running racine-codemod [codemodName] without specifying a path argument.

Manual migration strategies

Our codemods automate as much of a migration as possible and fall back to other strategies for cases that require manual intervention.

One strategy is inserting code comments. These comments help you locate and track cases where manual migration is necessary. You can delete the comments as you complete manual updates. The comment will always include the name of the codemod that added it. This behavior can be disabled by adding --addComments=false when running a codemod.

Additionally, some codemods include the ability to substitute in a shim component for cases that require manual updates. A shim component can help to bridge the gap while you track down the manual code changes needed to fully migrate your code. We do not provide shim components, only the functionality to rename a component to the shim component's name and add the necessary import statement. We strongly recommend migrating all usages of your shim component as soon as possible. Codemods that support shim components will accept shimName and shimImportPath arguments.

Shim component example

This is an example of a shim component that you could create in your codebase to use with the icon-library codemod. In this example, the shimName argument would be IconShim and the shimImportPath argument would be src/components/IconShim.

// src/components/IconShim.js
import {Icon} from '@sproutsocial/racine';
import {GeneralIconNames, ExternalIconNames, SproutIconNames} from '@sproutsocial/seeds-icons';
import IconMap from '@sproutsocial/racine/codemods/artifacts/icon-map.json';
import logoList from '@sproutsocial/racine/dist/logoList';
const allIconNames = [...GeneralIconNames, ...ExternalIconNames, ...SproutIconNames, ...logoList];

/** @deprecated This shim component is for temporary use while migrating to the new @sproutsocial/seeds-icons library. Do not add usages. */
export const IconShim = ({name, ...rest}) => {
  // If name is a valid icon name from the new library, render as-is.
  if (allIconNames.includes(name)) {
    return <Icon {...rest} name={name} />;
  }

  // If name was not a valid name, try to map it from the old library to the new one.
  const newName = IconMap[name];

  // If it's not in IconMap either, it's an invalid icon name.
  if (!newName) {
    // Include logging here to help you find instances where an invalid icon name is passed
    return null;
  }

  // Include logging here to help you find instances where an old icon name is passed and should be updated.
  return <Icon {...rest} name={newName} />;
};