https://github.com/obweger/modster
A plugin system and CLI for consuming and executing jscodeshift codemods, in a way that is not terrible.
https://github.com/obweger/modster
cli codemod codemods jscodeshift plugin
Last synced: 5 months ago
JSON representation
A plugin system and CLI for consuming and executing jscodeshift codemods, in a way that is not terrible.
- Host: GitHub
- URL: https://github.com/obweger/modster
- Owner: obweger
- License: mit
- Created: 2020-05-01T11:12:55.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-12-15T17:48:28.000Z (almost 2 years ago)
- Last Synced: 2025-04-30T03:47:29.243Z (5 months ago)
- Topics: cli, codemod, codemods, jscodeshift, plugin
- Language: TypeScript
- Homepage:
- Size: 193 KB
- Stars: 13
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Modster
> Codemoding, the easy way.
Modster is a plugin system and CLI for consuming and executing [`jscodeshift`](https://github.com/facebook/jscodeshift) codemods, in a way that is not terrible.
In Modster, you pick your codemod from a list of codemods, answer a few questions to have it configured, choose a file or directory to run against - and off you go!
Easy? Yes, much. ✌️
See the full run.
## Installation
E.g. using `yarn`:
```shell
$ yarn install modster
$ yarn modster
```
## Configuration
### `.codemods.js`
Modster is configured via a configuration file, typically named `.codemods.js`. It is expected to export an object with the following fields:
| Field | Type | Required | Description |
|- |-|-|-|
| `packageManager` | `string` | ✅ | Your package manager; typically `yarn` or `npm`. |
| `sourceDirectory` | `string` | ✅ | The directory on which you want codemods to operate. You can further limit the scope of a codemod when running Modster. |
| `extensions` | `string[]` | ✅ | The file extensions you want to run codemods against. Passed to `jscodeshift` as the `--ext` option. |
| `parser` | `string` | ✅ | The parser to use for parsing source files. One of `babel \| babylon \| flow \| ts \| tsx`. Passed to `jscodeshift` as the `--parser` option. |
| `plugins` | `string[]` | ✅ | A list of Modster plugins, following the [`eslint`-style plugin naming convention](https://github.com/obweger/plugin-name-to-package-name). See below for a list of existing plugins and how to create your own plugins. |
| `postUpdateTasks` | `function` | | A function of the shape `(updatedFiles: string[]) => { name: string; cmd: string }[]`, receiving the list of files modified by a codemod, and return a list of tasks to be executed. Every task has a `name` (e.g. `prettier`) and a `command` to be executed (e.g. `yarn run prettier ...`). |
Like so.
```js
export default {
packageManager: 'yarn',
extensions: ['tsx', 'ts'],
sourceFolder: 'src',
parser: 'tsx',
plugins: [
'hello-world'
],
postUpdateTask: (files: string[]) => [
{
name: 'eslint autofix',
command: `yarn eslint ${files.join(' ')} --ext tsx,ts --fix`
}
]
}
```
### CLI options
Modster takes two optional CLI options, `--config `, and `--dry`.
| Option | Description |
|-|-|
| `--config ` | The path to Modster's configuration file, relative to `process.cwd()`. Defaults to `./codemods`. |
| `--dry` | If set, runs `jscodeshift` in a dry run. Post-update tasks are printed but not executed. |
## Plugins
Modster uses a plugin system to consume codemods, similar to how e.g. `eslint` consumes linting rules. It is important to understand that Modser comes with no built-in codemod functionality; running Modster without plugins therefore doesn't make a huge amount of sense. But good news! - using and even writing Modster plugins is dead simple:
### Existing plugins
To consume a Modster plugin, you simply install it as an `npm` package, e.g. using `yarn`:
```shell
$ yarn install modster-plugin-hello-world
```
... and add it to your `.codemods.js`, following the [`eslint`-style plugin naming convention](https://github.com/obweger/plugin-name-to-package-name):
```diff
module.exports = {
// ...
plugins: [
// ...
+ 'hello-world'
]
}
```
See below for a list of Modster plugins:
| Plugin | Description |
|-|-|
| [Hello World](https://github.com/obweger/modster-plugin-hello-world) | A minimal plugin example; mostly a reference for [developing new plugins](./docs/developing-plugins/README.md). |
_To add a plugin to this list, please raise a PR._
### Developing plugins
See [Developing Modster plugins](./docs/developing-plugins/README.md).
## Contributions
Yes please!