Skip to main content

Contribution

This page covers 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 codeshift package automatically by running: yarn codeshift: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 codeshift package will look like this:

community/react-cool-library/
codeshift.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 '@codeshift/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 codeshift/cli.

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