Introduction
Hypermod (prev CodeshiftCommunity) is a community-owned global registry and documentation hub for codemods. This project provides users and maintainers of libraries with tools and resources to help them write, test, publish and use codemods in a structured and familiar way. By providing a standardized platform for codemod authoring, publishing, and consumption, Hypermod aims to promote the use of codemods as a standard development practice and reduce the learning curve for these tools.
Why?
Keeping JavaScript dependencies up-to-date is an important part of maintaining a healthy codebase. Outdated dependencies can introduce security vulnerabilities, cause compatibility issues, and make it difficult to use the latest features and improvements.
One way to keep your dependencies up-to-date is by using codemods. A codemod is a tool that can automatically refactor code, which can be particularly useful when making large-scale changes to a codebase.
For example, let's say you want to update the lodash library in your codebase from version 4 to version 5. This would require updating all of the import statements, function calls, and other references to lodash in your code. Instead of manually updating each instance, you can use a codemod to do the work for you.
To use a codemod for this task, you would provide it with the old and new code for lodash, as well as the files or directories that you want to update. The codemod would then scan your code and make the necessary changes. This can save you a significant amount of time and effort.
Additionally, using a codemod for this task can help ensure that your code stays consistent and up-to-date. By automatically updating all of the references to lodash, you can avoid any potential issues that may arise from using a mix of old and new code.
Of course, it is important to carefully review the changes made by a codemod to avoid any potential errors. However, in general, codemods can be a powerful tool for keeping your JavaScript dependencies up-to-date. They can save time, ensure consistency, and help keep your codebase healthy.
Objectives
Our main aim is to create a community centered around codemods in order to promote the use of codemods as a standard development practice across the JavaScript ecosystem.
We believe that providing the appropriate support, documentation, and tools can help us achieve this goal.
To accomplish this, Hypermod aims to address three key challenges:
- Fragmentation in how codemods are written and distributed within the ecosystem
- Difficulty adopting and upgrading packages
- Lack of documentation and understanding about codemods.
Fragmentation in the ecosystem
Hypermod offers a platform-agnostic toolchain for creating, publishing, and using codemods, centered around the @hypermod/cli. This CLI provides common infrastructure and eliminates the need for developers to constantly recreate the same tools.
Some popular libraries in the ecosystem, such as React, material-ui and next.js, all offer their own solutions for codemods, CLI, and distribution services. These services are inconsistent and often difficult for the average user to access. While providing these services can be helpful for upgrading libraries, it also places a significant burden on the projects that offer them.
Hypermod aims to address this issue by providing a standardized platform for codemod authoring, publishing, and consumption. This will help to reduce fragmentation and make it easier for developers to access the tools they need.
Package adoption & upgrade pain
When publishing API changes, it is easy to shift the burden of upgrading onto your users. This can lead to users having to search through your changelog or even your code to figure out how to migrate to the latest version safely. In many cases, users will simply avoid upgrading or switch to a different library altogether.
Hypermod offers a standardized versioning scheme that presents codemods in a user-friendly way. By following our guiding principles, your codemods will be idempotent, atomic, and reusable for years to come.
Writing a changelog and constantly answering the same questions about how to migrate can be time-consuming and frustrating. By distilling all of the necessary changes into a codemod, you can provide users with a repeatable, updatable solution that can be improved and perfected, with the help of the community. This allows you to focus on more important tasks and avoid the headache of supporting users through the upgrade process.
Lack of documentation & familiarity
Writing codemods can often feel like a specialized skill that only a few people in a company know how to do. Hypermod aims to change this by providing a hub for documentation and guidance.
By offering guides, recipes, and reference materials, we hope to demystify codemods and make them more accessible to everyone. With the right documentation in place, it will be easier to normalize the use of codemods and reduce their learning curve.
Our goal is to remove the stigma that codemods are difficult or time-consuming to write, and encourage everyone to adopt the practice of writing them. This will help to increase the number of contributors to codemods and ultimately improve the adoption of new technologies in the JavaScript ecosystem.
What we offer
A standardized CLI
Hypermod allows developers to publish codemods as their own NPM packages or as part of an existing NPM package. We provide a standardized CLI tool that can download and run the latest codemods from any location. This approach has the added benefit of allowing codemods to be published with dependencies, which is not currently possible with most JSCodeshift CLI implementations.
By using NPM, we aim to make it easy for developers to adopt codemods. All they need to do is publish an existing package with a codemod.config.js file and they are ready to go. For more information, see our guide on authoring with existing packages.
A centralized registry
DefinitelyTyped is a great example of how consolidating type definitions in one place can promote familiarity and consistency for the entire TypeScript user base. By following a similar approach for codemods, the ecosystem can benefit from:
- A single location for finding, using, and publishing codemods
- Community support and bug fixes
- A wealth of examples to learn from
Our goal is to achieve broad coverage of common JS dependencies, such as React, Jest, and Chalk, by collaborating with the wider JS community to produce high-quality, versioned codemods.
Hypermod offers a registry that hosts and automatically publishes codemods under the /community directory. This directory organizes codemods by package name and version, and publishes them to npm as modules that can be updated or improved. This ensures that users who run codemods always have access to the latest version.
Rich documentation
Hypermod is focused on providing documentation, guides, recipes, and reference materials to demystify codemods and make them more accessible. By offering this guidance, we hope to make it easier for developers to use codemods and reduce the learning curve.
We want to remove the perception that codemods are difficult or time-consuming to write, and encourage everyone to adopt the practice of using them. By doing so, we aim to increase the number of contributors to codemods and ultimately improve the adoption of new technologies in the JavaScript ecosystem.