External Packages

This page covers creation of stand-alone Hypermod packages and is for authors who want:

• Control over where and how your Hypermod package is hosted
• Control over tooling, dependencies and techstack
• The option to create completely generic codemods that don't target specific packages

Overview

Hypermod packages are standalone NPM packages that contain codemods and presets. They can be published to the NPM registry and consumed by the @hypermod/cli.

Hypermod packages are a great way to share codemods with the community, and can be used to create generic codemods that can be applied to any codebase.

Initializing

To create a standalone Hypermod package automatically, install the install and use the hypermod/cli.

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

Then given you want to initialize a new project called "foobar", with a codemod targeting version 10.0.0 you can run the following command:

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

This will create a new directory called "foobar" in the ~/Desktop directory.

You can then also initialize subsequent transforms and presets by running the command again:

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

File structure

The file structure of your new hypermod package will look like this:

react-cool-library/
  hypermod.config.js // main entrypoint containing configuration and references to your transforms
  package.json
  tsconfig.json
  jest.config.js
  codemods/
    10.0.0/ // semver version
      transform.ts // main logic (should contain a transformer)
      transform.spec.ts // main tests
      motions/ // utility directory

Writing a transformer

To write a transformer (aka codemod), please refer to the Your first codemod guide.

Testing

Now to test your transformer, run yarn test --watch.

See the Testing guide for help getting started with unit tests.

Publishing

Since your new hypermod package can simply be treated as an NPM package you can simply run npm version [patch\minor\major] and npm publish.

Your package will now be accessible via the @hypermod/cli. You can now download and execute your codemod on any codebase.

Running

Running a codemod as a consumer can now be done via the @hypermod/cli, assuming your package is named @monorepo/my-package and your codemod is 1.0.0:

$ hypermod --packages @monorepo/my-package@1.0.0 /path/to/source

You can even omit the codemod name to be prompted with all codemods as an interactive list:

$ hypermod --packages @monorepo/my-package /path/to/source

For more information on how to run codemods, please refer to the Running Codemods guide and the @hypermod/cli API reference.

Examples

Here are some helpful example of this setup working in the wild:

• Compiled codemods
• Webdriver.io codemods