config.md

Configuration

When running esformatter executable on the terminal, it will look for the closest .esformatter file and use that as a setting unless you specify --preset default or --config ./path/to/config_file.json.

You also have the option to put your esformatter settings inside the package.json file under the esformatter property.

property names

Most of the property names are based on the babel-eslint node types. For a list of node types you can also check the estree spec.

Our default settings should have all the names that we recognize, even if we don't list them in all the places the config probably use the same ids on all the settings (indent, lineBreak and whiteSpace), don't get intimidated by the names!

root

Settings from multiple files will be merged until it finds a config file that contains the property "root": true; that makes it easy to define exceptions to the project/global rules without needing to copy all the shared properties. For an example see test files inside the "test/compare/rc" folder.

{
  "root": true
}

protip: set "esformatter": {"root": true} inside the project package.json (or .esformatter file ) to avoid conflicts between contributor settings (it will avoid loading the global user config).

indent

Indent is responsible for whitespace at the front of each line. indent.value is used for each indentation. The default indents with two spaces. Setting indent.value to "\t" will switch to indentation using tabs. If you want to set indentation to 4 spaces, set indent.value to " " (literal string with 4 spaces)

The other properties for indent toggle indentation for specific elements. These all refer to regular JavaScript statements except for TopLevelFunctionBlock. This is enabled by default, with no special behaviour. When disabled (set to 0), esformatter will not indent top level function blocks (used by the jQuery preset).

• negative integer (-1 till -99): decrease indent level by [n].
• 0: don't increase or decrease indent level.
• positive integer (1 till 99): increase indent level by [n].

{
  "indent": {
    "value": "\t",
    "FunctionExpression": 1,
    "ArrayExpression": 0,
    "ObjectExpression": 0
  }
}

If the node.type is not listed on the indent configuration we assume its value is set to 0 and we won't increase/decrease the indent level of that block/expression.

PS: we always replace the original file indentation to simplify the process, specially because adding/removing linebreaks changes drastically the indentation of the blocks.

lineBreak

The default lineBreak.value is "\n".

For lineBreak you can use ranges or integers:

• -1: keep original line breaks.
• 0: remove line breaks.
• positive integer (1 till 99): "add or keep [n] line breaks".
• ">2": add linebreaks until it's over 2.
• ">=1": add line breaks until it's equal or greater than 1.
• "<2": remove linebreaks until it's smaller than 2.
• "<=1": remove/add line breaks until it's smaller or equal to 1.

The property names mostly match the names used by the Abstract Syntax Tree (AST) for JavaScript. A lot of them have "...Opening", "...Closing", "...OpeningBrace" and "...ClosingBrace" as variants, allowing very fine grained control over each settings.

{
  "lineBreak": {
    "before": {
      "FunctionDeclaration": ">=1",
      "FunctionDeclarationOpeningBrace": 0,
      "FunctionDeclarationClosingBrace": 1
    },
    "after": {
      "FunctionDeclaration": ">=1",
      "FunctionDeclarationOpeningBrace": 1
    }
  }
}

whiteSpace

The default whiteSpace.value is a single space (" "). Its unlikely that you ever need to change this.

For whiteSpace you can set values to:

• -1: keep the original value.
• 0: remove all white spaces.
• positive integers (1 till 99): add/keep [n] spaces.

{
  "whiteSpace": {
    "before": {
      "FunctionExpressionOpeningBrace": 1,
      "FunctionExpressionClosingBrace": 1
    },
    "after": {
      "FunctionExpressionOpeningBrace": 1,
      "FunctionExpressionClosingBrace": -1
    }
  }
}

Important to note that we don't insert white spaces at the beginning or end of the lines, so in the above example we would only add a space before } if it is not the first char of the line, and only insert a space after { if it is not followed by a line break.

pipe

Since we don't expect everyone to write plugins that only works with esformatter we decided to support the usage of standalone CLI tools.

{
  // pipe is a simple way to "pipe" multiple binaries input/output
  "pipe": {
    // scripts listed as "before" will be executed before esformatter
    // and will forward output to next command in the queue
    "before": [
      "strip-debug",
      "./bin/my-custom-script.sh --foo true -zx"
    ],
    // scripts listed as "after" will be executed after esformatter
    "after": [
      "baz --keepLineBreaks"
    ]
  }
}

The pipe option works by passing the string input to stdin of the first executable and piping the stdout->stdin of each tool. The executables will be executed in the same order as they are listed, before or after the default esformatter transformations.

The pipe option works similar to npm run-script, where it locates the locally installed executables inside the node_modules folder. If it can't find a local executable it will fallback to global commands. (this allows you to install devDependencies that are only used by a single project)

PS: piped commands are usually slower than esformatter plugins because they usually require parsing the file another time and spawning new processes isn't cheap. But it might still be a good way to reuse existing scripts.

plugins

Plugins are automatically loaded from node_modules if you pass the module id in the config file:

{
  // executes plugins in the same order as listed in the Array
  "plugins": [ "esformatter-sample-plugin", "foobar" ]
}

For detailed information about plugins structure and API see plugins.md

extends

Extends allows users to share presets easily.

{
  "extends": [
    "preset:foobar", // load "esformatter-preset-foobar" from "./node_modules"
    "./lorem_ipsum.json" // load relative config file
  ]
}

Read the presets.md file for info on how to write reusable configs.

---

Documenting each property here wouldn't be practical. For now we recommend you look at the lib/preset/default.js to find the properties you need to adjust for your specific needs. Better yet, adopt one of the presets to avoid having to configure anything beyond the most basic settings (like indent.value).

Live preview on Requirebin