Skip to main content
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:

​
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/create-require-from-path@1.1.0

# 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

​
Prerequisites

Before publishing, you need to:
  1. Create a Codemod package – Use npx codemod init to scaffold a new package. Learn more about building Codemod packages.
  2. Authenticate – Login to the registry using npx codemod login. Learn more about authentication.

​
Publishing Your First Package

# 1. Navigate to your codemod directory
cd my-codemod

# 2. Publish (first publish must be interactive)
npx codemod publish
During the first publish, you’ll be prompted to:
  • Choose an organization or user scope
  • Set access level (public or private)
  • Confirm package metadata
Most packages do not need a scope, but use a scoped name if you are distributing official Codemod packages for a framework or library, or if you are an enterprise team distributing Codemod packages across your organization. Scoped codemods support features like organization-private visibility.
Unpublishing packages: 
# Unpublish a specific version
npx codemod unpublish <package-name> --version 1.0.0

# Unpublish all versions (requires --force)
npx codemod unpublish <package-name> --force
Unpublishing is a destructive action. Consider deprecating packages instead of unpublishing if others may depend on them. You must use --version to unpublish a specific version, or --force to unpublish all versions.
Learn more about the publish and unpublish commands.

​
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.

​
Publishing from CI/CD

The easiest way to set up CI/CD publishing is to use the migrations template repository.

Migrations Template

The migrations template repository includes a preconfigured GitHub Action workflow for automatic publishing.
 This GitHub template includes:
  • Preconfigured GitHub Action workflow for automatic publishing
  • Setup instructions for GitHub App installation and API key configuration
  • Repository structure optimized for codemod packages
After setup, codemods are automatically published to the registry when PRs are merged. See the template repository for complete setup instructions.

​
Using Packages in Workflows

You can reference registry packages in your workflow definitions:
workflow.yaml
steps:
  - name: Run registry codemod
    codemod:
      source: "@nodejs/create-require-from-path@1.1.0"
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.

Codemod Registry

Browse and discover packages in the web interface.