How to install ESLint in a JavaScript project

The prerequisite for any Node.js-based tooling, including ESLint, is a package.json manifest file at the root of the project directory. This file serves as the canonical descriptor for the project, defining its dependencies, scripts, and other metadata. Without it, managing the dependency graph becomes an ad-hoc, non-repeatable process. If your project lacks this file, the first operation is to generate it.

The command to execute in your terminal is straightforward:

npm init -y

The -y flag bypasses the interactive questionnaire, accepting the default values for all fields. This generates a minimal, functional package.json. The resulting file structure will be a simple JSON object, similar to the following:

{
  "name": "your-project-name",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo "Error: no test specified" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

This file is the bedrock. All subsequent tooling, including the ESLint package itself, will be registered here as a development dependency. This ensures that any developer checking out the repository can install the exact same set of tools with a single command, leading to a deterministic build and analysis environment. Only with this foundation in place can we proceed to the actual installation of the linter, which will modify this file to include its own entry.

The installation command sequence

With the manifest in place, the core ESLint package can be added to the project. The correct mechanism is through npm, specifying the package as a development dependency. This is not code that runs as part of the application in a production environment; it is a tool used during the development phase. The distinction is critical.

npm install eslint --save-dev

Executing this command modifies the package.json file, adding a devDependencies block and registering ESLint with its current version. The file will now contain a section like this:

"devDependencies": {
  "eslint": "^8.56.0"
}

The caret (^) prefix indicates that npm can install compatible minor and patch versions, but not major versions that could introduce breaking changes. This ensures a stable but up-to-date tooling environment across the development team.

Simply installing the package is insufficient. ESLint requires a configuration file to define the rules it will enforce. While this file can be created manually, the most efficient path is to use ESLint’s own initialization utility. This script guides you through a series of questions to generate a baseline configuration tailored to your project’s specific technology stack.

The command to trigger this interactive setup is:

npm init @eslint/config

This command downloads and executes the @eslint/config package. The terminal will then present a series of prompts. For instance:

✔ How would you like to use ESLint? · style
✔ What type of modules does your project use? · esm
✔ Which framework does your project use? · react
✔ Does your project use TypeScript? · No / Yes
✔ Where does your code run? · browser
✔ How would you like to define a style for your project? · guide
✔ Which style guide do you want to follow? · standard
✔ What format do you want your config file to be in? · JSON

Based on these answers, the initializer not only creates the configuration file (e.g., .eslintrc.json) but also installs any required plugins and parsers as additional development dependencies. For a React project, this would include packages like eslint-plugin-react. The result is a project with a functional linter, ready for rule customization. The generated configuration file contains the initial set of directives derived from your selections, forming the basis for our explicit rule definitions.

The explicit definition of linting rules

The configuration file generated by the initialization command, typically named .eslintrc.json, is the control plane for ESLint’s static analysis engine. It’s a JSON object containing directives that determine which rules are active, their severity, and the environment in which the code executes. A baseline configuration is established by the extends property, which imports rule sets from shared configurations. For example, "eslint:recommended" provides a vetted set of rules that catch common JavaScript errors.

The true power lies in the explicit override and definition of rules within the rules object in this file. This object allows for fine-grained control, superseding any rules inherited from the extends array. This is where a project’s specific coding standards are encoded into an enforceable contract.

Each key in the rules object corresponds to a specific ESLint rule identifier. The value assigned to the key dictates its enforcement level. The system recognizes three distinct levels:

• "off" or 0: The rule is completely disabled.
• "warn" or 1: A violation of the rule will produce a warning message during the linting process but will not cause the process to fail (i.e., it will exit with a status code of 0).
• "error" or 2: A violation will produce an error message and cause the linting process to exit with a non-zero status code, which is typically interpreted as a failure in CI/CD pipelines.

Consider a scenario where the base configuration enforces the use of curly braces for all control statements, a rule identified as curly. If the project standard allows for single-line if statements without braces, this rule can be reconfigured. The default might be "curly": "error". To change this, you would add an entry to your local rules object.

{
  "extends": "eslint:recommended",
  "rules": {
    "curly": ["error", "multi-line"]
  }
}

In this configuration, the value for the curly rule is an array. The first element, "error", sets the severity. The second element, "multi-line", is an option specific to the curly rule, instructing it to enforce braces only when the statement block spans multiple lines. This is a common pattern for rules that require more than a simple on/off switch.

Another example is managing quotes. A project might standardize on single quotes for all strings. The quotes rule can enforce this:

{
  "rules": {
    "quotes": ["error", "single"]
  }
}

This configuration mandates single quotes and will report an error for any string literal that uses double quotes, unless the string itself contains a single quote. The explicit definition of these rules removes ambiguity from the development process. Code style is no longer a matter of opinion or discussion during a code review; it is an automated check. The linter becomes the objective arbiter of the established standard, ensuring that every commit adheres to the same structural and stylistic principles. This deterministic approach is fundamental to building scalable and maintainable software systems. You can systematically add rules to enforce best practices, such as preventing the use of console.log in production code.

{
  "rules": {
    "no-console": "warn"
  }
}

Setting this to "warn" provides a useful reminder during development without breaking local builds, while a CI environment could be configured to treat warnings as errors. The flexibility to define rules and their severity allows the configuration to be tailored precisely to the project’s workflow and quality gates. The .eslintrc.json file becomes the canonical source of truth for code quality standards, versioned alongside the source code itself.

Automating the lint pass with npm scripts

Manually executing the ESLint command from the terminal is inefficient and prone to error. The correct approach is to encapsulate the linting logic within an npm script, defined in the package.json file. The scripts object in this file serves as a project-specific command registry, providing aliases for common development tasks.

To integrate ESLint, we define a lint script. This script will invoke the ESLint executable, which is available in the project’s local node_modules/.bin directory. npm automatically adds this directory to the path when running scripts, so we can call eslint directly.

The most basic linting script targets all files within the project directory:

{
  "scripts": {
    "lint": "eslint ."
  }
}

With this definition in place, any developer can run the linter with a standardized command: npm run lint. The command eslint . instructs ESLint to start linting from the current directory and traverse downwards, analyzing all JavaScript files it encounters. It automatically respects the configuration in .eslintrc.json and any ignore patterns specified in an .eslintignore file.

This abstraction is non-trivial. It ensures that every team member executes the exact same analysis, with the same flags and targets. For more complex projects, the command can be made more specific. For instance, to only lint files within the src directory and include files with a .jsx extension:

{
  "scripts": {
    "lint": "eslint src/ --ext .js,.jsx"
  }
}

A significant capability of ESLint is its ability to automatically correct certain rule violations. This mechanism handles stylistic issues like indentation, spacing, and quote consistency without manual intervention. To leverage this, we add a separate script, conventionally named lint:fix.

{
  "scripts": {
    "lint": "eslint src/ --ext .js,.jsx",
    "lint:fix": "eslint src/ --ext .js,.jsx --fix"
  }
}

The --fix flag instructs ESLint to modify the source files directly to conform to the rules. This is a powerful optimization for the development loop. A developer can write code without obsessing over formatting minutiae, then execute npm run lint:fix to mechanically align the entire codebase with the project’s standards. This automates a class of changes that would otherwise consume developer time and create noise in code reviews. The system enforces the standard, not a person.