diff --git a/doc/presets.md b/doc/presets.md new file mode 100644 index 0000000..8b1c5c5 --- /dev/null +++ b/doc/presets.md @@ -0,0 +1,73 @@ +# Presets + +Presets are reusable config files that can `require` other presets/plugins and +override configs. + +## Reusing presets + +On your [esformatter config file](./config.md) you can do; + +```js +{ + // presets are used as "base settings" + "extends": [ + "preset:foobar", // load "esformatter-preset-foobar" from "./node_modules" + "./lorem_ipsum.json" // load relative config file + ], + + // you can still override any setting from the preset if needed + "indent": { + "value": " " + } +} +``` + +Note that the `preset:` pseudo-protocol will try to find the module with the +`esformatter-preset-` prefix. That should make it easier to find presets on npm. + + +## Authoring presets + +List all the preset dependencies on the `package.json`, that way consumers of +your preset only need to list the preset as dependency: + +```js +{ + // use the `esformatter-preset-` prefix on the name + "name": "esformatter-preset-foobar", + // list all the dependencies + "dependencies": { + "esformatter-quotes": "^1.0.3", + "esformatter-preset-dolor": "^1.0.0" + } +} +``` + +And the implementation would be something like: + +```js +// need to use `require` because dependencies will be listed +// on the preset "package.json" +module.exports = { + + // extend other presets + extends: [ + require('esformatter-preset-dolor'), + require('./foo-settings') + ], + + // register plugins + plugins: [ + require('esformatter-quotes') + ], + + // this will override any values set by the `esformatter-preset-dolor` and + // `./foo-settings` + indent: { + value: '\t' + } +}; +``` + +protip: we use this feature on [lib/preset/default.js](../lib/preset/default.js) +to increase organization.