Codemod Registry

The Codemod Registry is a centralized repository for discovering, consuming, and distributing Codemod packages. It enables the community to share reusable code transformation tools and allows organizations to maintain private codemods for their internal use. It provides:

Package discovery – Search and browse codemods by language, framework, category, and keywords
Version management – Semantic versioning with support for version pinning
Scoped packages – Organize packages by organization or user scope (e.g., @nodejs/create-require-from-path)
Access control – Configure codemod access types: public or private
Direct execution – Run packages directly from the registry using npx codemod <package-name>

Package Access Types

Codemod packages can have different access levels that control who can discover and run them:

Public Access

Packages with public access are discoverable and runnable by anyone. They appear in public search results and can be used by the entire community. Use cases:

Community-shared codemods for open-source projects
Framework migration tools for public use
Educational or example codemods

Features:

Free to use and publish
Discoverable by everyone
Browse at codemod.com/registry

Private Access

Packages with private access are only accessible to the owner or organization members. Available for Pro and Enterprise plan customers. Use cases:

Maintain proprietary codemods for company-specific patterns
Share internal codemods across teams
Keep sensitive transformations private
Enforce organization standards

Access:

Requires organization membership (for organization-scoped packages)
Packages can be scoped to your organization (e.g., @your-org/internal-codemod)
Configured through organization settings in the Codemod app

To use a scoped package name, first reserve the scope by installing the Codemod GitHub App on a repository in your GitHub organization. Only organization admins can publish codemods under that scope.

Discovering Packages

Browse the Registry: Visit the Codemod Registry web interface to browse packages. Search from CLI: Use the codemod search command to find packages:

# Search for packages
npx codemod search [query]

Learn more about search options in the CLI Reference.

Running Packages from the Registry

Run packages directly from the registry without downloading them first:

# Run a package (scoped or unscoped)
npx codemod @nodejs/create-require-from-path

When you run a package from the registry, Codemod CLI automatically downloads and caches it locally. Subsequent runs use the cached version for faster execution.

Version Pinning: For reproducible runs in production, always specify an exact version:

# Pin to specific version
npx codemod @nodejs/[email protected]

# Uses latest version (may change)
npx codemod @nodejs/create-require-from-path

Version pinning ensures your codemods behave consistently across different environments and over time.

Publishing Packages

Publish your codemods to the registry to share them with others or use them across projects.

# 1. Create a codemod package
npx codemod init

# 2. Login to the registry
npx codemod login

# 3. Publish your codemod
npx codemod publish

Publishing Guide

Learn about all publishing methods: interactive login, API keys, and trusted publishers for CI/CD.

Configuring Access and Visibility

In your codemod.yaml, configure registry settings:

codemod.yaml

registry:
  access: "public"      # or "private"
  visibility: "public"  # or "private", "org", "user"

Access levels:

public – Anyone can run the codemod
private – Only the owner can run the codemod

Pro codemods are reserved for Codemod and their partners. To learn more, contact the Codemod team.

Visibility levels:

public – Everyone can see the package in search and listings
private – Only the owner can see the package
org – Members of the package’s organization scope can see it
user – Visible only to the publishing user

Access and visibility work together. For example, visibility: public with access: private shows the package publicly, but only the owner can run it.

Learn more about configuring packages.

Using Packages in Workflows

You can reference registry packages in your workflow definitions:

workflow.yaml

steps:
  - name: Run registry codemod
    codemod:
      source: "@nodejs/[email protected]"

Learn more about using Codemod packages in workflows.

Best Practices

Package Naming

Use descriptive names that indicate the codemod’s purpose
Follow the naming convention: /^[a-z0-9-_/]+$/
Include framework/library names when relevant

When to use scoped package names: Use scoped package names (e.g., @your-org/package-name) when:

Framework or library maintainers publishing official codemods for your project
Organizations or teams publishing multiple related codemods that should be grouped together
You want to ensure only your organization can publish codemods with that scope
You need better discoverability for codemods from a specific organization or framework

For individual developers or one-off codemods, unscoped package names are usually the best choice.

Versioning

Follow semantic versioning (MAJOR.MINOR.PATCH)
Increment major version for breaking changes
Increment minor version for new features
Increment patch version for bug fixes

Documentation

Write clear descriptions in codemod.yaml
Add relevant keywords for discoverability
Include examples in your README
Document any workflow parameters

Testing

Test your codemod thoroughly before publishing
Use jssg testing for automated test cases
Validate your workflow with npx codemod workflow validate
Test with real codebases before publishing

Next steps

CLI Reference

Complete command reference for registry operations.

Building Workflows

Learn how to create and configure Codemod packages.

Browse and discover packages in the web interface.

First steps

Enterprise

Community

Other Resources