Command line tool to help you keep configuration (package.json
, .gitignore
, .eslintrc
, etc.) of your open source projects in sync.
- Will not overwrite your data if you don’t want it to
- Minimal changes: will keep the original file formatting or read the style from EditorConfig
- Minimal configuration: will try to infer configuration from the project itself or from the environment
- Bunch of customizable tasks included
- Tools to work with JSON, YAML, INI, Markdown and new line separated text files
- Easy to write your own tasks
- Share tasks via npm and group them into presets
- Motivation
- Installation
- Usage
- Usage via npx
- Configuration
- Tasks
- Writing your own tasks
- Sharing tasks via npm
- Custom presets
- Config resolution rules
- Task resolution rules
- FAQ
- Change log
- Contributing
- Authors and license
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.
Read more in my article, Automating open source project configuration with Mrm, or watch my talk on Mrm.
npm install -g mrm
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 "[email protected]" --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
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 "[email protected]" --config:url "http://middleearth.com"
Create ~/.mrm/config.json
or ~/dotfiles/mrm/config.json
:
{
"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", "editorconfig", "gitignore"]
}
}
See tasks docs for available config options.
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.
These tasks are included by default:
- codecov
- contributing
- editorconfig
- eslint
- gitignore
- jest
- license
- lint-staged
- package
- prettier
- readme
- semantic-release
- styleguidist
- stylelint
- travis
- typescript
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 a default one.
The simplest task could look like this:
// Mrm module to work with new line separated text files
const { lines } = require('mrm-core');
function task() {
// Read .gitignore if it exists
lines('.gitignore')
// Add lines that do not exist in a file yet,
// but keep all existing lines
.add(['node_modules/', '.DS_Store'])
// Update or create a file
.save();
}
task.description = 'Adds .gitignore';
module.exports = task;
Tasks can also be async by adding the async
keyword or returning a Promise
.
async function task () {
}
// or
function task () {
return new Promise(() => {
})
}
If your 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.
Let’s take a look at a more complicated task:
const {
// JSON files
json,
// package.json
packageJson,
// New line separated text files
lines,
// Install npm packages
install
} = require('mrm-core');
function task(config) {
// Task options
// mrm eslint --config:name pizza
const { name, eslintPreset } = config
.defaults({
// Default value
eslintPreset: 'eslint:recommended'
})
// Required option
.require('name')
.values();
// Use custom preset package from npm
const packages = ['eslint'];
if (eslintPreset !== 'eslint:recommended') {
packages.push(`eslint-config-${eslintPreset}`);
}
// Create or update .eslintignore
lines('.eslintignore')
.add(['node_modules/'])
.save();
// Read project’s package.json
const pkg = packageJson();
pkg
// Add lint script
.setScript('lint', 'eslint . --cache --fix')
// Add pretest script
.prependScript('pretest', 'npm run lint')
.save();
// Read .eslintrc if it exists
const eslintrc = json('.eslintrc');
// Use Babel parser if the project depends on Babel
if (pkg.get('devDependencies.babel-core')) {
const parser = 'babel-eslint';
packages.push(parser);
eslintrc.merge({ parser });
}
// Set preset
eslintrc.set('extends', eslintPreset).save();
// Install npm dependencies
install(packages);
}
task.description = 'Adds ESLint';
module.exports = task;
There are more methods in mrm-core
— check out the docs and the default tasks.
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
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
<DIR>/config.json
if--dir <DIR>
command line option was passed$HOME/dotfiles/mrm/config.json
$HOME/.mrm/config.json
if you’re passing a --preset <PRESET>
command line option, then the only task directory will be:
mrm-preset-<PRESET>/config.json
<DIR>/<TASK>/index.js
if--dir <DIR>
command line option was passed$HOME/dotfiles/mrm/<TASK>/index.js
$HOME/.mrm/<TASK>/index.js
mrm-task-<TASK>/index.js
, wheremrm-task-<TASK>
is an npm package name<TASK>
in mrm-preset-default
if you’re passing a --preset <PRESET>
command line option, then the only task directory will be:
mrm-preset-<PRESET>/<TASK>/index.js
To run a task for each package in a Lerna repository:
./node_modules/.bin/lerna exec -- mrm <TASK>
Use the user-meta package to read user name, email and URL from .npmrc
or .gitconfig
:
const meta = require('user-meta');
module.exports = function task(config) {
const { name, email, url } = config
.defaults(meta)
.require('name', 'email', 'url')
.values();
/* ... */
}
Use the git-username package:
const gitUsername = require('git-username');
module.exports = function task(config) {
const { github } = config
.defaults({
github: gitUsername(),
})
.require('github')
.values();
/* ... */
}
The change log can be found on the Releases page.
Everyone is welcome to contribute. Please take a moment to review the contributing guidelines.
Artem Sapegin and contributors.
MIT License, see the included License.md file.