Configuration

Every Hypermod package requires a hypermod.config.js file. This file serves as the entry point for your package, containing essential metadata and defining the paths to the transformer functions.

A typical configuration looks like this:

module.exports = {
  maintainers: ['danieldelcore'],
  description: 'Codemods for the foobar package',
  targets: ['foobar'],
  transforms: {
    '18.0.0': require('./18.0.0/transform'),
    '19.0.0': require('./19.0.0/transform'),
  },
  presets: {
    'sort-imports': require('./sort-imports/transform'),
  },
};

When publishing codemods via npm, ensure that Hypermod files are located in the root directory of your package. This allows @hypermod/cli to retrieve them by fetching your package from npm and scanning the root directory. To avoid issues, confirm that the config and transform files are included in your package and not ignored by npm via .npmignore.

To verify your configuration, use the validate command.

The CLI will search for config files in the following locations:

• hypermod.config.(js|ts|tsx)
• src/hypermod.config.(js|ts|tsx)
• codemods/hypermod.config.(js|ts|tsx)

You can write the configuration file in either JavaScript, TypeScript or TSX.

Properties

maintainers

Github usernames of the people that maintain the package, they will be notified on PRs etc.

description

A description of the package and its intended usage

transforms

A key value pair of transforms organized by semver-compatible versions.

For more information see guiding principles.

presets

A key value pair of presets organized by kebab case identifiers.

Presets are intended to act as a way to share generic codemods, that are either completely generic or compliment the target package but are not version specific.

Some examples include: sort-imports, format-props, remove-comments, etc.

targets

(Experimental API)

Targets list the packages that the codemod package targets. This is useful for Hypermod packages that have codemods targeting multiple related packages at the same time, such as packages from a monorepo.

For example: targets: ['@foo/bar', '@foo/baz']

dependencies

The dependencies field specifies the dependencies required by the codemod files. This is useful when co-locating codemods with an existing npm package, as it allows you to avoid listing codemod-specific dependencies as dependencies in the main package, which would otherwise increase the bundle size.

By using the dependencies field, you can whitelist the dependencies used specifically by the codemods to be installed.

Note: The dependencies listed in this field must be installed in the package.json under the devDependencies section for this to work correctly.

For example:

package.json

{
  "name": "my-package",
  "version": "1.0.0",
  "dependencies": {
    "react": "^17.0.0"
  },
  "devDependencies": {
    // This is a dependency used only by the codemods
    "codemod-specifc-utility": "^0.1.0"
  }
}

hypermod.config.js

module.exports = {
  description: 'Codemods for the my-package package',
  transforms: {
    '1.0.0': require('./1.0.0/transform'),
  },
  dependencies: ['codemod-specifc-utility']
};