mrm

Mrm

Command line tool to help you keep configuration (package.json, .gitignore, .eslintrc, etc.) of your open source projects in sync.

Features

• Will not overwrite your data if you don’t want it to
• Tools to work with JSON, YAML, INI, Markdown and text files
• Bunch of customizable tasks included
• Easy to write your own tasks
• Share tasks via npm and group them into presets

Table of contents

• Motivation
• Installation
• Usage
• Usage via npx
• Configuration
• Tasks
• Writing custom tasks
• Sharing tasks via npm
• Custom presets
• Config resolution rules
• Task resolution rules
• Work with Lerna
• Change log
• Contributing
• Authors and license

Motivation

Most of the available tools are template based. Template approach works moderately well for new project generation but doesn’t work well for updating. Mrm’s approach is closer to codemods than templates.

Installation

npm install -g mrm

Usage

Print a list available of tasks:

mrm

Run a task or an alias

mrm gitignore
mrm license

Run multiple tasks:

mrm gitignore license

Override config options (or run without a config file):

mrm license --config:name "Gandalf the Grey" --config:email "[e-mail]" --config:url "http://middleearth.com"

Custom config and tasks folder:

mrm license --dir ~/unicorn

Run a task from a preset (globally installed mrm-preset-unicorn npm package, read more about preset):

mrm license --preset unicorn

Usage via npx

If you have npm 5.3 or newer you can use mrm without installation:

npx mrm
npx mrm gitignore
npx mrm license --config:name "Gandalf the Grey" --config:email "[e-mail]" --config:url "http://middleearth.com"

Configuration

Create ~/.mrm/config.json or ~/dotfiles/mrm/config.json:

{
  "name": "Gandalf the Grey",
  "email": "[e-mail]",
  "url": "http://middleearth.com",
  "indent": "tab", // "tab" or number of spaces
  "readmeFile": "Readme.md", // Name of readme file
  "licenseFile": "License.md", // Name of license file
  "aliases": {  // Aliases to run multiple tasks at once
    "node": ["license", "readme", "package", "editorconfig", "eslint", "gitignore"]
  }
}

Config file isn’t required, you can also pass config options via command line. Default tasks will try to read data fom your npm and Git configuration.

Tasks

These tasks are included by default:

• codecov
• editorconfig
• eslint
• gitignore
• jest
• license
• lintstaged
• package
• readme
• semantic-release
• styleguidist
• stylelint
• travis
• typescript

Writing custom tasks

Create either ~/.mrm/<TASK>/index.js or ~/dotfiles/mrm/<TASK>/index.js. If <TASK> is the same as one of the default tasks your task will override an internal one.

const { /* ... */ } = require('mrm-core');
const meta = require('user-meta');
function task(config, argv) {
  const { name, email } = config
    .defaults({ name: meta.name }) // Set “dynamic” default values (this will affect require() method below)
    .require('name', 'email') // Mark config values as required
    .values(); // Returns object with all config options
  // argv - command line arguments
};
task.description = 'Task description';
module.exports = task;

If your custom tasks have dependencies (such as mrm-core) you should initialize the mrm folder as an npm module and list your dependencies there:

cd ~/.mrm # or cd ~/dotfiles/mrm
npm init -y
npm install --save mrm-core

mrm-core is an utility library created to write Mrm tasks, it has function to work with common config files (JSON, YAML, INI, Markdown), npm dependencies, etc.

You can find some examples here or check code of default tasks.

Sharing tasks via npm

The basic file structure of a shared task looks like this:

.
├── index.js
├── package.json

index.js is the same as described in the previous section. And the package.json would look like this:

{
  "name": "mrm-task-unicorn",
  "version": "0.1.0",
  "description": "Unicorn task for Mrm",
  "author": {
    "name": "Artem Sapegin",
    "url": "http://sapegin.me"
  },
  "homepage": "https://github.com/sapegin/mrm-tasks/packages/mrm-task-unicorn",
  "repository": "sapegin/mrm-tasks",
  "license": "MIT",
  "engines": {
    "node": ">=4"
  },
  "main": "index.js",
  "files": [
    "index.js"
  ],
  "keywords": [
    "mrm",
    "mrm-task",
    "unicorn"
  ],
  "dependencies": {
    "mrm-core": "^2.1.3"
  }
}

The package name should should follow this pattern: mrm-task-<TASK>, otherwise you’ll have to type full package name when you run a task:

mrm unicorn # mrm-task-unicorn
mrm @mycompany/unicorn-task # @mycompany/unicorn-task

Custom presets

Preset is an npm package (or a directory) that contains a config and tasks.

The file structure looks like this:

.
├── task1
│   └── index.js
├── task2
│   └── index.js
├── config.json
├── package.json

And the package.json would look like this:

{
  "name": "mrm-preset-default",
  "version": "0.1.0",
  "description": "Common tasks for Mrm",
  "author": {
    "name": "Artem Sapegin",
    "url": "http://sapegin.me"
  },
  "homepage": "https://github.com/sapegin/mrm-tasks/packages/mrm-preset-default",
  "repository": "sapegin/mrm-tasks",
  "license": "MIT",
  "engines": {
    "node": ">=4"
  },
  "main": "config.json",
  "files": [
    "config.json",
    "*/index.js"
  ],
  "keywords": [
    "mrm",
    "mrm-task",
    "mrm-preset"
  ],
  "dependencies": {
    "mrm-core": "^2.1.3",
    "mrm-task-gitignore": "^0.1.0"
  }
}

See the Writing custom tasks section above to learn how to write Mrm tasks. To add a task to a preset put it into a <TASK>/index.js file in your preset package folder.

If you want to use a task from npm (or any default task), you should include it as a dependency. That way you can be sure that you’ll always have a task version that works for your project.

For example, if you want to use mrm-task-gitignore task, you need to create a gitignore/index.js file in your preset package folder:

module.exports = require('mrm-task-gitignore');

The package name should should follow this pattern: mrm-preset-<TASK>, otherwise you’ll have to type full package name when you run a task:

mrm license --preset unicorn # mrm-preset-unicorn
mrm license --preset @mycompany/unicorn-preset # @mycompany/unicorn-preset

Config resolution rules

• <DIR>/config.json if --dir <DIR> command line option was passed
• $HOME/dotfiles/mrm/config.json
• $HOME/.mrm/mrm/config.json
• mrm-preset-default/config.json

if you’re passing a --preset <PRESET> command line option, then the only task directory will be:

• mrm-preset-<PRESET>/config.json

Task resolution rules

• <DIR>/<TASK>/index.js if --dir <DIR> command line option was passed
• $HOME/dotfiles/mrm/<TASK>/index.js
• $HOME/.mrm/mrm/<TASK>/index.js
• mrm-preset-default/<TASK>/index.js

if you’re passing a --preset <PRESET> command line option, then the only task directory will be:

• mrm-preset-<PRESET>/<TASK>/index.js

Work with Lerna

To run a task for each package in a Lerna repository:

./node_modules/.bin/lerna exec -- mrm <TASK>

Change log

The change log can be found on the Releases page.

Contributing

Everyone is welcome to contribute. Please take a moment to review the contributing guidelines.

Authors and license

Artem Sapegin and contributors.

MIT License, see the included License.md file.