Skip to main content

Contribution

This page covers the process of authoring and publishing codemods, including tips and best practices for creating high-quality codemods that others can use and benefit from.

It is intended to explain in detail contribution to the public registry and is for authors who want:

  • Codemods to be open source
  • Build tooling, dependency management and project setup to be handled for you
  • The community to help maintain and contribute to your codemods
  • Documentation to be automatically generated and available on the Registry page

If you prefer to create codemods outside of this repo, please see the Authoring guide for other options.

Getting setup​

To get setup, first fork this repository and clone it to your local machine. Make sure you have the correct version of node and yarn(1.x) installed. Finally, run yarn to install the dependencies.

Initializing​

Create a new hypermod package automatically by running: yarn hypermod:init -p [package-name] -v [version]

For example: yarn community:init react-cool-library 10.0.0

And for scoped packages: yarn community:init @scope/react-cool-library 10.0.0

You should now see a new folder within the /community directory for you to implement your codemod(s).

File structure​

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

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

Writing a transformer​

The logic for your codemod should be added to the transform.ts file.

Transformers are the main entrypoint to your codemod, they are responsible for accepting a raw file, applying the appropriate modifications to it and finally outputting the resulting AST to the original file.

Example:

import { hasImportDeclaration } from '@hypermod/utils';

export default function transformer(file, { jscodeshift: j }, options) {
  const source = j(file.source);

  if (!hasImportDeclaration(j, source, 'my')) {
    return file.source; // Writes original untouched file
  }

  // Do transformation logic here...

  return source.toSource(options.printOptions); // Writes modified AST to file
}

For a more detailed guide, please refer to the Your First Codemod guide.

Testing​

Now to test your transformer, run yarn test:watch community/[package-name].

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

  • Make sure to write a healthy amount of unit tests
  • This is a great opportunity for test driven development
  • Consider different edge-cases, idempotency, different languages (js, flow, typescript)
  • Before you share your changes with the world, be sure to use it yourself

Publishing​

Once you're happy with your new package and you've tested it appropriately, it's time to raise a PR.

When the PR is reviewed and merged, your new package will automatically be published and available via the hypermod/cli.

Refer to the Consuming guide for information about how to run your new codemods.