hypermod/cli

To download and run codemods, we provide a CLI tool called @hypermod/cli.

@hypermod/cli is responsible for running the provided transform against your entire codebase. Under the hood, it is a wrapper of jscodeshift's CLI, which provides additional functionality

1. Ability to run community codemods hosted on npm
2. Runs versioned codemods in sequence
3. Always runs the latest version of a codemod

The CLI allows you to run transforms either from the the public registry or on your local machine as per the original implementation of jscodeshift

Note: Codemods will be designed to do the heavy lifting, but they'll often not be perfect so some manual work may still be required in order to successfully migrate.

Usage/Installation

We recommend running the CLI with $ npx to ensure you always have the latest version.

$ npx @hypermod/cli --packages mylib@1.0.0 /project/src

But it can also be installed globally:

$ npm install -g @hypermod/cli or yarn global add @hypermod/cli

and run with:

$ hypermod or $ hypermod-cli

default

The default CLI command (when no subcommand is specified,) will attempt to download and run transform(s) against the specified file path.

In the majority of cases you want to be sure to either provide the --packages flag for running remote codemods, or the --transform, -t flag to run a local transform file.

For running codemods as an end-user it's recommend to use the --packages flag, which accepts the following format: --packages [package-name]@[semver-version]. For example, running the codemod to migrate your codebase to react version 18.0.0 you would specify the following --packages react@18.0.0.

In special cases, Hypermod package authors may choose to also expose codemod "presets", which can be considered as utility codemods for that package. Presets are also run via the --packages flag like so: --packages react#remove-spread-props. Notice that we have switched to a hash # here to denote that we want to run a preset.

Hypermod will then attempt to locate codemods from both the public registry and the primary npm package ie React – NPM. (Note: Some packages wont have any codemods, you can use the list subcommand to check if they exist.)

Lastly, when authoring a package, it's possible to test your transforms by omitting both the --packages and --transform flags. In this interactive mode, the hypermod/cli will attempt to locate a local hypermod.config.js from the current or parent directories and present an interactive prompt for you to choose from.

example:

Run a transform for "@mylib/button" version 3.0.0 only

• $ hypermod --packages @mylib/button@3.0.0 /project/src

Run a transform for "@mylib/button" preset foo-bar only

• $ hypermod --packages @mylib/button#foo-bar /project/src

Run all transforms for "@mylib/button" greater than version 3.0.0 and @mylib/range greater than 4.0.0

• $ hypermod --sequence --packages @mylib/button@3.0.0,@mylib/range@4.0.0 /project/src

Run the "my-custom-transform" transform

• $ hypermod -t path/to/my-custom-transform /project/src

Display a prompt with a list of codemods from my local hypermod.config.js file(s).

• $ hypermod /project/src

--transform, -t

Allows you to execute local transform file(s).

• Can be provided with a comma-separated list (see example below).
• Transforms can be either a single file or directory containing an "index" file.

example:

• $ hypermod --transform codemods/my-special-mod /project/src/file.js
• $ hypermod --transform codemods/my-special-mod/index.ts /project/src/file.js
• $ hypermod --transform path/to/transform1.ts,path/to/transform2.ts,path/to/transform3.ts /project/src/file.js

--packages

Runs transforms for the specified comma separated list of packages, optionally include a version for each package to run all transforms since that version

example:

• $ hypermod --packages @atlaskit/button /project/src
• $ hypermod --packages @atlaskit/button@3.0.0,@atlaskit/range@4.0.0 /project/src

--parser, -p

Parser to use for parsing the source files you are code modding.

options:

• babel
• babylon
• flow
• ts
• tsx (default)

default:

tsx

tsx is a superset of JavaScript + JSX and should be the most sensible default for modern codebases.

example:

• $ hypermod --parser tsx /project/src/file.ts
• $ hypermod -p babel /project/src/file.js

--extensions, -e

Transform files with these file extensions (comma separated list).

default:

js, jsx, ts, tsx

example:

• $ hypermod --extensions ts,tsx /project/src/file.js
• $ hypermod -e js /project/src/file.js

--sequence, -s

If the package flag is provided, runs all transforms from the provided version to the latest.

default:

false

example:

• $ hypermod --packages @atlaskit/button@3.0.0 --sequence /project/src

--ignore-pattern

Ignore files that match a provided glob expression

default:

• **/node_modules/**

example:

• $ hypermod --ignore-pattern node_modules /project/src/file.js

--verbose

Show more information about the transform process

default:

• 0

example:

• $ hypermod --verbose 2 /project/src/file.js

--version, -v

Get current version number

example:

• $ hypermod --version
• $ hypermod -v

--registry

If an alternative registry url is provided, all packages will be fetched from this registry.

default:

https://registry.npmjs.org/

example:

• $ hypermod --registry https://private-registry.npmjs.org/

--registryToken

If a registry token is provided, it will be used as an authentication token for the registry.

example:

• $ hypermod --registryToken <ACCESS_TOKEN>

--help

Print all help text to the command line

example:

• $ hypermod --help

list

Subcommand that lists available codemods for the provided packages

example:

Print a list of available codemods for a single package

• $ hypermod list mylib

Print a list of available codemods for multiple packages

• $ hypermod list @atlaskit/avatar @emotion/monorepo

init

Subcommand that generates a new codemod at your desired path

example:

Create a new Hypermod package called foobar with a transform for version 10 on the Desktop

• $ hypermod init --version="10.0.0" ~/Desktop/foobar

Create an empty hypermod package called on the Desktop

• $ hypermod init ~/Desktop/foobar

Create an empty hypermod package called foobar in the current directory

• $ hypermod init

Create a 'config only' hypermod package in the current directory

• $ hypermod init --config-only .

--config-only (optional)

Only output a configuration file.

example:

Initializes a configuration file only

• `$ hypermod init --config-only path/to/src``

Initializes a configuration file and preset source code

• `$ hypermod init --config-only --preset update-imports path/to/src``

--version (optional)

A semver-compatible string. Will be used to generate mock transform files and configuration.

example:

Create a codemod package called foobar with a versioned transform.

• $ hypermod init --package-name="foobar" --version="10.0.0" ~/Desktop

--preset (optional)

A kebab-cased string. Will be used to generate mock transform files and configuration.

example:

Create a codemod package called foobar with a preset.

• $ hypermod init --package-name="foobar" --preset="sort-imports" ~/Desktop

validate

Subcommand that validates a codemod package at the desired path.

example:

Validate a codemod package called "my-codemods".

• $ hypermod validate ./codemods/my-codemods

Validate a codemod package from the current working directory

• $ hypermod validate