eslint/docs/src/use/getting-started.md

   1 ---
   2 title: Getting Started with ESLint
   3 eleventyNavigation:
   4     key: getting started
   5     parent: use eslint
   6     title: Getting Started
   7     order: 1
   8
   9 ---
  10
  11 ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code, with the goal of making code more consistent and avoiding bugs.
  12
  13 ESLint is completely pluggable. Every single rule is a plugin and you can add more at runtime. You can also add community plugins, configurations, and parsers to extend the functionality of ESLint.
  14
  15 ## Prerequisites
  16
  17 To use ESLint, you must have [Node.js](https://nodejs.org/en/) (`^12.22.0`, `^14.17.0`, or `>=16.0.0`) installed and built with SSL support. (If you are using an official Node.js distribution, SSL is always built in.)
  18
  19 ## Quick start
  20
  21 You can install and configure ESLint using this command:
  22
  23 ```shell
  24 npm init @eslint/config
  25 ```
  26
  27 If you want to use a specific shareable config that is hosted on npm, you can use the `--config` option and specify the package name:
  28
  29 ```shell
  30 # use `eslint-config-semistandard` shared config
  31
  32 # npm 7+
  33 npm init @eslint/config -- --config semistandard
  34
  35 # or (`eslint-config` prefix is optional)
  36 npm init @eslint/config -- --config eslint-config-semistandard
  37
  38 # ⚠️ npm 6.x no extra double-dash:
  39 npm init @eslint/config --config semistandard
  40
  41 ```
  42
  43 The `--config` flag also supports passing in arrays:
  44
  45 ```shell
  46 npm init @eslint/config -- --config semistandard,standard
  47 # or
  48 npm init @eslint/config -- --config semistandard --config standard
  49 ```
  50
  51 **Note:** `npm init @eslint/config` assumes you have a `package.json` file already. If you don't, make sure to run `npm init` or `yarn init` beforehand.
  52
  53 After that, you can run ESLint on any file or directory like this:
  54
  55 ```shell
  56 npx eslint yourfile.js
  57
  58 # or
  59
  60 yarn run eslint yourfile.js
  61 ```
  62
  63 ## Configuration
  64
  65 **Note:** If you are coming from a version before 1.0.0 please see the [migration guide](migrating-to-1.0.0).
  66
  67 After running `npm init @eslint/config`, you'll have an `.eslintrc.{js,yml,json}` file in your directory. In it, you'll see some rules configured like this:
  68
  69 ```json
  70 {
  71     "rules": {
  72         "semi": ["error", "always"],
  73         "quotes": ["error", "double"]
  74     }
  75 }
  76 ```
  77
  78 The names `"semi"` and `"quotes"` are the names of [rules](../rules) in ESLint. The first value is the error level of the rule and can be one of these values:
  79
  80 * `"off"` or `0` - turn the rule off
  81 * `"warn"` or `1` - turn the rule on as a warning (doesn't affect exit code)
  82 * `"error"` or `2` - turn the rule on as an error (exit code will be 1)
  83
  84 The three error levels allow you fine-grained control over how ESLint applies rules (for more configuration options and details, see the [configuration docs](configure/)).
  85
  86 Your `.eslintrc.{js,yml,json}` configuration file will also include the line:
  87
  88 ```json
  89 {
  90     "extends": "eslint:recommended"
  91 }
  92 ```
  93
  94 Because of this line, all of the rules marked "(recommended)" on the [rules page](../rules) will be turned on.  Alternatively, you can use configurations that others have created by searching for "eslint-config" on [npmjs.com](https://www.npmjs.com/search?q=eslint-config).  ESLint will not lint your code unless you extend from a shared configuration or explicitly turn rules on in your configuration.
  95
  96 ## Global Install
  97
  98 It is also possible to install ESLint globally, rather than locally, using `npm install eslint --global`. However, this is not recommended, and any plugins or shareable configs that you use must still be installed locally if you install ESLint globally.
  99
 100 ## Manual Set Up
 101
 102 You can also manually set up ESLint in your project.
 103
 104 Before you begin, you must already have a `package.json` file. If you don't, make sure to run `npm init` or `yarn init` to create the file beforehand.
 105
 106 1. Install the ESLint package in your project:
 107
 108    ```shell
 109    npm install --save-dev eslint
 110    ```
 111
 112 1. Add an `.eslintrc` file in one of the [supported configuration file formats](./configure/configuration-files#configuration-file-formats).
 113
 114    ```shell
 115    # Create JavaScript configuration file
 116    touch .eslintrc.js
 117    ```
 118
 119 1. Add configuration to the `.eslintrc` file. Refer to the [Configure ESLint documentation](configure/) to learn how to add rules, environments, custom configurations, plugins, and more.
 120
 121    ```js
 122    // .eslintrc.js example
 123    module.exports = {
 124      "env": {
 125          "browser": true,
 126          "es2021": true
 127      },
 128      "extends": "eslint:recommended",
 129      "parserOptions": {
 130          "ecmaVersion": "latest",
 131          "sourceType": "module"
 132      },
 133    }
 134    ```
 135
 136 1. Lint code using the ESLint CLI:
 137
 138    ```shell
 139    npx eslint project-dir/ file1.js
 140    ```
 141
 142    For more information on the available CLI options, refer to [Command Line Interface](./command-line-interface).
 143
 144 ---
 145
 146 ## Next Steps
 147
 148 * Learn about [advanced configuration](configure/) of ESLint.
 149 * Get familiar with the [command line options](command-line-interface).
 150 * Explore [ESLint integrations](integrations) into other tools like editors, build systems, and more.
 151 * Can't find just the right rule?  Make your own [custom rule](../extend/custom-rules).
 152 * Make ESLint even better by [contributing](../contribute/).