eslint/docs/developer-guide/shareable-configs.md

   1 # Shareable Configs
   2
   3 The configuration that you have in your `.eslintrc` file is an important part of your project, and as such, you may want to share it with other projects or people. Shareable configs allow you to publish your configuration settings on [npm](https://www.npmjs.com/) and have others download and use it in their ESLint projects.
   4
   5 ## Creating a Shareable Config
   6
   7 Shareable configs are simply npm packages that export a configuration object. To start, [create a Node.js module](https://docs.npmjs.com/getting-started/creating-node-modules) like you normally would. Make sure the module name begins with `eslint-config-`, such as `eslint-config-myconfig`.
   8
   9 npm [scoped modules](https://docs.npmjs.com/misc/scope) are also supported, by naming or prefixing the module with `@scope/eslint-config`, such as `@scope/eslint-config` or `@scope/eslint-config-myconfig`.
  10
  11 Create a new `index.js` file and export an object containing your settings:
  12
  13 ```js
  14 module.exports = {
  15
  16     globals: {
  17         MyGlobal: true
  18     },
  19
  20     rules: {
  21         semi: [2, "always"]
  22     }
  23
  24 };
  25 ```
  26
  27 Since `index.js` is just JavaScript, you can optionally read these settings from a file or generate them dynamically.
  28
  29 ## Publishing a Shareable Config
  30
  31 Once your shareable config is ready, you can [publish to npm](https://docs.npmjs.com/getting-started/publishing-npm-packages) to share with others. We recommend using the `eslint` and `eslintconfig` keywords so others can easily find your module.
  32
  33 You should declare your dependency on ESLint in `package.json` using the [peerDependencies](https://docs.npmjs.com/files/package.json#peerdependencies) field. The recommended way to declare a dependency for future proof compatibility is with the ">=" range syntax, using the lowest required ESLint version. For example:
  34
  35 ```json
  36 {
  37     "peerDependencies": {
  38         "eslint": ">= 3"
  39     }
  40 }
  41 ```
  42
  43 If your shareable config depends on a plugin, you should also specify it as a `peerDependency` (plugins will be loaded relative to the end user's project, so the end user is required to install the plugins they need). However, if your shareable config depends on a third-party parser or another shareable config, you can specify these packages as `dependencies`.
  44
  45 You can also test your shareable config on your computer before publishing by linking your module globally. Type:
  46
  47 ```bash
  48 npm link
  49 ```
  50
  51 Then, in your project that wants to use your shareable config, type:
  52
  53 ```bash
  54 npm link eslint-config-myconfig
  55 ```
  56
  57 Be sure to replace `eslint-config-myconfig` with the actual name of your module.
  58
  59 ## Using a Shareable Config
  60
  61 Shareable configs are designed to work with the `extends` feature of `.eslintrc` files. Instead of using a file path for the value of `extends`, use your module name. For example:
  62
  63 ```json
  64 {
  65     "extends": "eslint-config-myconfig"
  66 }
  67 ```
  68
  69 You can also omit the `eslint-config-` and it will be automatically assumed by ESLint:
  70
  71 ```json
  72 {
  73     "extends": "myconfig"
  74 }
  75 ```
  76
  77 ### npm scoped modules
  78
  79 npm [scoped modules](https://docs.npmjs.com/misc/scope) are also supported in a number of ways.
  80
  81 By using the module name:
  82
  83 ```json
  84 {
  85     "extends": "@scope/eslint-config"
  86 }
  87 ```
  88
  89 You can also omit the `eslint-config` and it will be automatically assumed by ESLint:
  90
  91 ```json
  92 {
  93     "extends": "@scope"
  94 }
  95 ```
  96
  97 The module name can also be customized, just note that when using [scoped modules](https://docs.npmjs.com/misc/scope) it is not possible to omit the `eslint-config-` prefix. Doing so would result in package naming conflicts, and thus in resolution errors in most of cases. For example a package named `@scope/eslint-config-myconfig` vs `@scope/myconfig`, since both are valid scoped package names, the configuration should be specified as:
  98
  99 ```json
 100 {
 101     "extends": "@scope/eslint-config-myconfig"
 102 }
 103 ```
 104
 105 You can override settings from the shareable config by adding them directly into your `.eslintrc` file.
 106
 107 ## Sharing Multiple Configs
 108
 109 It's possible to share multiple configs in the same npm package. You can specify a default config for the package by following the directions in the first section. You can specify additional configs by simply adding a new file to your npm package and then referencing it from your ESLint config.
 110
 111 As an example, you can create a file called `my-special-config.js` in the root of your npm package and export a config, such as:
 112
 113 ```js
 114 module.exports = {
 115     rules: {
 116         quotes: [2, "double"]
 117     }
 118 };
 119 ```
 120
 121 Then, assuming you're using the package name `eslint-config-myconfig`, you can access the additional config via:
 122
 123 ```json
 124 {
 125     "extends": "myconfig/my-special-config"
 126 }
 127 ```
 128
 129 When using [scoped modules](https://docs.npmjs.com/misc/scope) it is not possible to omit the `eslint-config` namespace. Doing so would result in resolution errors as explained above. Assuming the package name is `@scope/eslint-config`, the additional config can be accessed as:
 130
 131 ```json
 132 {
 133     "extends": "@scope/eslint-config/my-special-config"
 134 }
 135 ```
 136
 137 Note that you can leave off the `.js` from the filename. In this way, you can add as many additional configs to your package as you'd like.
 138
 139 **Important:** We strongly recommend always including a default config for your plugin to avoid errors.
 140
 141 ## Local Config File Resolution
 142
 143 If you need to make multiple configs that can extend from each other and live in different directories, you can create a single shareable config that handles this scenario.
 144
 145 As an example, let's assume you're using the package name `eslint-config-myconfig` and your package looks something like this:
 146
 147 ```text
 148 myconfig
 149 ├── index.js
 150 └─┬ lib
 151   ├── defaults.js
 152   ├── dev.js
 153   ├── ci.js
 154   └─┬ ci
 155     ├── frontend.js
 156     ├── backend.js
 157     └── common.js
 158 ```
 159
 160 In your `index.js` you can do something like this:
 161
 162 ```js
 163 module.exports = require('./lib/ci.js');
 164 ```
 165
 166 Now inside your package you have `/lib/defaults.js`, which contains:
 167
 168 ```js
 169 module.exports = {
 170     rules: {
 171         'no-console': 1
 172     }
 173 };
 174 ```
 175
 176 Inside your `/lib/ci.js` you have
 177
 178 ```js
 179 module.exports = require('./ci/backend');
 180 ```
 181
 182 Inside your `/lib/ci/common.js`
 183
 184 ```js
 185 module.exports = {
 186     rules: {
 187         'no-alert': 2
 188     },
 189     extends: 'myconfig/lib/defaults'
 190 };
 191 ```
 192
 193 Despite being in an entirely different directory, you'll see that all `extends` must use the full package path to the config file you wish to extend.
 194
 195 Now inside your `/lib/ci/backend.js`
 196
 197 ```js
 198 module.exports = {
 199     rules: {
 200         'no-console': 1
 201     },
 202     extends: 'myconfig/lib/ci/common'
 203 };
 204 ```
 205
 206 In the last file, you'll once again see that to properly resolve your config, you'll need include the full package path.
 207
 208 ## Further Reading
 209
 210 * [npm Developer Guide](https://docs.npmjs.com/misc/developers)