editorconfig

What is editorconfig?

The editorconfig npm package is used to parse and apply editor configuration from .editorconfig files. These files are designed to maintain consistent coding styles across different editors and IDEs for a project. The package helps in reading the .editorconfig file and applying the configurations to the code editor.

What are editorconfig's main functionalities?

Parse .editorconfig files

This feature allows you to parse an .editorconfig file to retrieve the configurations for a given file path. The parse function returns a promise that resolves with the configuration object.

const editorconfig = require('editorconfig');
editorconfig.parse(filePath).then(config => {
  console.log(config);
});

Parse from a specific position in a file

This feature is useful when you want to get the configuration that applies from a specific line number in a file. It can be helpful when dealing with files that may have different configurations at different positions.

const editorconfig = require('editorconfig');
editorconfig.parse(filePath, { start: lineNumber }).then(config => {
  console.log(config);
});

Generate editor configurations

This feature allows you to generate the contents of an .editorconfig file based on a given configuration object. The generate function returns a promise that resolves with the string content of the .editorconfig file.

const editorconfig = require('editorconfig');
const configs = {
  indent_style: 'space',
  indent_size: 2
};
editorconfig.generate(configs).then(content => {
  console.log(content);
});

Other packages similar to editorconfig

prettier

Prettier is an opinionated code formatter that supports many languages and integrates with most editors. Unlike editorconfig, which focuses on maintaining consistent coding styles, Prettier reformats your code according to its own set of rules, which can be customized.

eslint

ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code. It is more comprehensive than editorconfig as it can enforce coding standards and also find problematic patterns or code that doesn’t adhere to certain style guidelines.

stylelint

Stylelint is a modern linter that helps you avoid errors and enforce conventions in your stylesheets. It is similar to editorconfig but is specifically designed for CSS, SCSS, and other styling languages, offering more detailed control over style rules.

README

EditorConfig JavaScript Core

The EditorConfig JavaScript core will provide the same functionality as the EditorConfig C Core and EditorConfig Python Core.

Installation

You need node to use this package.

To install the package locally:

$ npm install editorconfig

To install the package system-wide:

$ npm install -g editorconfig

Usage

Options

Most of the API takes an options object, which has the following defaults:

{
  config: '.editorconfig',
  version: pkg.version,
  root: '/',
  files: undefined,
  cache: undefined,
  unset: false,
};

config

The name of the config file to look for in the current and every parent directory.

version

Which editorconfig spec version to use. Earlier versions had different defaults.

root

What directory to stop processing in, even if we haven't found a file containing root=true. Defaults to the root of the filesystem containing `process.cwd()`.

files

Pass in an empty array, which will be filled with one object for each config file processed. The objects will have the shape `{filename: "[DIRECTORY]/.editorconfig", glob: "*"}`

cache

If you are going to process more than one file in the same project, pass in a cache object. It must have `get(string): object|undefined` and `set(string, object)` methods, like a JavaScript Map. A long-running process might want to consider that this cache might grow over time, and that the config files might change over time. However, we leave any complexity of that nature to the caller, since there are so many different approaches that might be taken based on latency, memory, and CPU trade-offs. Note that some of the objects in the cache will be for files that did not exist. Those objects will have a `notfound: true` property. All of the objects will have a `name: string` property that contains the fully-qualified file name of the config file and a `root: boolean` property that describes if the config file had a `root=true` at the top. Any other properties in the objects should be treated as opaque.

unset

If true, after combining all properties, remove all properties whose value remains as "unset". This is typically left for plugin authors to do, and the conformance tests assume that this value is always false.

in Node.js:

parse(filePath[, options])

Search for .editorconfig files starting from the current directory to the root directory. Combine all of the sections whose section names match filePath into a single object.

Example:

const editorconfig = require('editorconfig');
const path = require('path');

const filePath = path.join(__dirname, 'sample.js');

(async () => {
  console.log(await editorconfig.parse(filePath, {files: []}));
})();
/*
  {
    indent_style: 'space',
    indent_size: 2,
    end_of_line: 'lf',
    charset: 'utf-8',
    trim_trailing_whitespace: true,
    insert_final_newline: true,
    tab_width: 2
  };
  assert.deepEqual(files, [
    { fileName: '[DIRECTORY]/.editorconfig', glob: '*' },
    { fileName: '[DIRECTORY]/.editorconfig', glob: '*.js' }
  ])
*/

parseSync(filePath[, options])

Synchronous version of editorconfig.parse().

parseBuffer(fileContent)

The parse() function above uses parseBuffer() under the hood. If you have the contents of a config file, and want to see what is being processed for just that file rather than the full directory hierarchy, this might be useful.

parseString(fileContent)

This is a thin wrapper around parseBuffer() for backward-compatibility. Prefer parseBuffer() to avoid an unnecessary UTF8-to-UTF16-to-UTF8 conversion. Deprecated.

parseFromFiles(filePath, configs[, options])

Low-level interface, which exists only for backward-compatibility. Deprecated.

Example:

const editorconfig = require('editorconfig');
const fs = require('fs');
const path = require('path');

const configPath = path.join(__dirname, '.editorconfig');
const configs = [
  {
    name: configPath,
    contents: fs.readFileSync(configPath, 'utf8')
  }
];

const filePath = path.join(__dirname, '/sample.js');

(async () => {
  console.log(await editorconfig.parseFromFiles(filePath, Promise.resolve(configs)))
})();
/*
  {
    indent_style: 'space',
    indent_size: 2,
    end_of_line: 'lf',
    charset: 'utf-8',
    trim_trailing_whitespace: true,
    insert_final_newline: true,
    tab_width: 2
  };
*/

parseFromFilesSync(filePath, configs[, options])

Synchronous version of editorconfig.parseFromFiles(). Deprecated.

in Command Line

$ ./bin/editorconfig

Usage: editorconfig [options] <FILEPATH...>

Arguments:
  FILEPATH       Files to find configuration for.  Can be a hyphen (-) if you
                 want path(s) to be read from stdin.

Options:
  -v, --version  Display version information from the package
  -f <path>      Specify conf filename other than '.editorconfig'
  -b <version>   Specify version (used by devs to test compatibility)
  --files        Output file names that contributed to the configuration,
                 rather than the configuation itself
  -h, --help     display help for command

Example:

$ ./bin/editorconfig /home/zoidberg/humans/anatomy.md
charset=utf-8
insert_final_newline=true
end_of_line=lf
tab_width=8
trim_trailing_whitespace=sometimes

$ ./bin/editorconfig --files /home/zoidberg/humans/anatomy.md
/home/zoidberg/.editorconfig [*]
/home/zoidberg/.editorconfig [*.md]
/home/zoidberg/humans/.editorconfig [*]

Development

To install dependencies for this package run this in the package directory:

$ npm install

Next, run the following commands:

$ npm run build
$ npm link

The global editorconfig will now point to the files in your development repository instead of a globally-installed version from npm. You can now use editorconfig directly to test your changes.

If you ever update from the central repository and there are errors, it might be because you are missing some dependencies. If that happens, just run npm link again to get the latest dependencies.

To test the command line interface:

$ editorconfig <filepath>

Testing

CMake must be installed to run the tests.

To run the tests:

$ npm test

To run the tests with increased verbosity (for debugging test failures):

$ npm run ci

Changelog

2.0.0

• Breaking: Now requires Node v16+
• Enable extended globbing from minimatch. This means that some patterns will work in this version might not work in other editorconfig implementations. Fixes #84.
• Add unset option to API and CLI. When enabled, properties with the value "unset" will be removed from the returned object. Defaults to false in all cases, since according to the core team, this is something that the editor plugin is supposed to do, and the tests reinforce this. An unset() function is now exported if you'd like to call it explicitly. Fixes #123.