Skip to main content

Introduction

CodeshiftCommunity is a community-owned global registry and documentation hub for codemods. This project provides library users & maintainers with facilities to help write, test, publish and consume codemods in a structured and familiar way.

Why?

Our overarching goal is to build a community around codemods to help normalize both authoring and consuming them, turning it into a standard development practice throughout the JavaScript ecosystem.

We believe this can be achieved by making the right support, documentation and tooling available to everyone.

To do this CodeshiftCommunity aims to solve three main problems.

  1. Fragmentation of how codemods are written & distributed in the ecosystem
  2. Package adoption & upgrade pain
  3. Lack of documentation & familiarity

Fragmentation in the ecosystem

Popular libraries in the ecosystem such as React, material-ui and next.js, all provide their own take on codemods, CLI and distribution services. These services are varied from one another and generally quite hidden from the average user. Providing this as an additional service to aid in upgrading their libraries is a great thing, but comes with significant overhead to those projects.

Package adoption & upgrade pain

When publishing packages via semver, it is too easy to push the upgrade pain onto users. Users will likely then have to go digging in either your changelog or (worst case) your code to find out how to safely migrate to the latest and greatest. Often the solution is just to avoid upgrading entirely or migrate to a new library.

Lack of documentation & familiarity

Writing codemods often feels like tribal knowledge, there might be only a handfull of people in your company that have written one or know how to write one. This needs to change!

How do we solve these problems?

A standardized CLI

Codeshift works by publishing every codemod to NPM as its own package or piggybacking off a pre-existing NPM package. We provide a standardized CLI tool that can download and run the most up to date codemods from anywhere. With the hidden benefit of being able to publish with dependencies, currently something that is not possible with most JSCodeshift CLI implementations.

Using NPM drastically lowers the adoption bar, since all one would need to do is publish an existing package with a codemod.config.js and you're good to go. See Authoring with existing packages

A centralized registry

DefinitelyTyped is a great example of how consolidating type definitions under the one roof builds familiarity and consistency for the entire typescript user base.

By consolidating codemods in the same way, the ecosystem can benefit from:

  1. A single place to find, use and publish codemods
  2. Community support & bug fixes
  3. Countless examples

Ultimately, with the wider JS community collaborating to produce high quality versioned codemods, our goal is to achieve solid coverage over common js dependencies (ie react, jest, chalk, etc), in a similar way to how quality type definitions are created and shared within the DefinitelyTyped community.

CodeshiftCommunity provides a similar registry that hosts and automatically publishes codemods for you under the /community directory. The community directory organizes codemods by package name and version. They are then published to npm as modules that can be retrospectively patched or improved. This ensures that users running codemods are always getting the latest and greatest version of your codemod.

Rich documentation

CodeshiftCommunity is a documentation hub first, by providing guides, recipes and reference material we aim demystify codemods, which are often seen as "arcane knowledge".

With the right documentation and guidance in place, it will be significantly easier to normalize codemods and reduce their learning curve. We want to remove the stigma that "codemods are hard" or "they take a long time to write" and get everyone into the healthy practice of writing them. Meaning that more people can contribute to writing codemods and ultimately improve the javascript ecosystem's adoption problem.

Getting started