ESLint Adoption Guide: A Complete Framework for Code Quality

Installing and Configuring ESLint

Quick Start with npm init

The fastest way to get ESLint running in a new project is through the official initialization command. This interactive tool guides you through a series of questions to determine how you're using ESLint and what options should be included, as outlined in the ESLint getting started documentation.

npm init @eslint/config@latest

This command assumes you have a package.json file already. If you don't, make sure to run npm init or yarn init beforehand to create one. The initialization process asks about your target environment (browser, Node.js), preferred code style, and which rules you'd like to enable.

For projects using a specific shared configuration hosted on npm, you can specify that directly during initialization:

npm init @eslint/config@latest -- --config eslint-config-xo

Manual Installation and Setup

For more control over the installation process, you can set up ESLint manually. First, install the ESLint packages as dev dependencies:

npm install --save-dev eslint@latest @eslint/js@latest

Then create an eslint.config.js file in your project's root directory. The flat configuration format introduced in ESLint 9 uses JavaScript modules, so you'll want to use either .mjs extension or ensure your package.json has "type": "module" set.

import { defineConfig } from "eslint/config";
import js from "@eslint/js";

export default defineConfig([
 {
 files: ["**/*.js"],
 plugins: { js },
 extends: ["js/recommended"],
 rules: {
 "no-unused-vars": "warn",
 "no-undef": "warn",
 },
 },
]);

The extends property allows you to incorporate recommended rules from shared configurations, while the rules property lets you customize individual rules for your project's specific needs.

Integrating linting into your workflow pairs well with understanding modern CSS techniques like CSS padding for consistent styling across your projects.

Understanding Rule Severity Levels

ESLint provides three distinct severity levels for configuring rules, giving you fine-grained control over how violations are handled:

The "warn" or 1 severity enables a rule as a warning, which means violations will be reported but won't cause the linting process to fail. Warnings are useful for style preferences that don't necessarily indicate bugs or potential problems, as noted in the ESLint documentation.

The "error" or 2 severity treats violations as errors that will cause the linting process to return a non-zero exit code. This severity level is appropriate for rules that catch potential bugs, security vulnerabilities, or code that violates critical architectural decisions. Error-level rules integrate well with CI/CD pipelines, where they can block merges or deployments until violations are resolved.

Configuring Rules for Your Project

Individual rule configuration goes beyond simply setting severity levels. Many rules accept additional options that customize their behavior:

rules: {
 "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
 "no-undef": "error",
 "eqeqeq": ["error", "always"],
}

A well-configured ESLint setup typically uses a combination of all three severity levels, with warnings for style preferences and errors for actual problems.

TypeScript ESLint: Extending ESLint for TypeScript Projects

TypeScript has become the standard for large-scale JavaScript applications, and ESLint requires additional configuration to properly lint TypeScript code. The typescript-eslint project provides the essential tooling for this integration, including a parser that understands TypeScript syntax and a plugin that provides TypeScript-specific rules.

Installation for TypeScript Projects

npm install --save-dev eslint typescript typescript-eslint

TypeScript ESLint Configuration Presets

The typescript-eslint package provides several configuration presets:

• recommended: Rules broadly applicable and thoroughly tested
• strict: Builds on recommended with additional strict rules
• stylistic: Focuses on code style and formatting

import eslint from "@eslint/js";
import tseslint from "typescript-eslint";

export default tseslint.config(
 eslint.configs.recommended,
 ...tseslint.configs.recommended,
 {
 rules: {
 "@typescript-eslint/no-explicit-any": "warn",
 },
 },
);

The recommended preset includes rules that are broadly applicable and have been thoroughly tested across many projects. This is the recommended starting point for most projects, as it provides good coverage without being overly restrictive.

Understanding how ESLint integrates with TypeScript is essential when building modern web applications. Pair this with our guide on view transitions to create seamless user experiences.

Building a Team Adoption Strategy

Successfully adopting ESLint requires more than just technical configuration--it requires a strategy for introducing the tool to your team and maintaining the configuration over time. Teams that approach ESLint adoption thoughtfully see better results and fewer conflicts than those who simply enable strict rules without preparation, as discussed in LogRocket's comprehensive ESLint adoption guide.

Starting with a Baseline

When introducing ESLint to an existing codebase, it's important not to start with all rules enabled at their strictest levels. Instead, begin by running ESLint to establish a baseline of existing violations, then gradually enable and fix rules in phases. This approach prevents developers from being overwhelmed by thousands of violations and allows the team to focus on fixing one category of issues at a time.

Sharing Configurations Across Projects

Organizations with multiple projects benefit from sharing ESLint configurations through npm packages. This approach ensures consistency across teams and simplifies maintenance:

// @your-org/eslint-config/index.js
export default {
 rules: {
 // organization-wide rules
 }
};

Projects then import and extend this shared configuration, adding only project-specific overrides as needed. The shared configuration should be versioned semantically, with breaking changes only in major versions.

Integrating with Code Review

ESLint violations should appear in your code review process. Configure your review tools to display ESLint output directly in the review interface for maximum visibility. Many teams configure their code review tools to display ESLint output directly in the review interface, making it easy for reviewers to see violations without running ESLint locally.

IDE Integration and Development Workflow

The value of ESLint is maximized when it's integrated directly into developers' workflows, providing immediate feedback as they write code rather than requiring them to run a separate command, as explained in the LogRocket ESLint adoption guide.

VS Code Configuration

VS Code, the most popular editor for JavaScript and TypeScript development, offers an official ESLint extension that integrates seamlessly with your project's ESLint configuration. Once installed, the extension runs ESLint in the background and highlights violations directly in the editor, often with auto-fix support for common issues.

{
 "editor.codeActionsOnSave": {
 "source.fixAll.eslint": "explicit"
 },
 "eslint.useFlatConfig": true
}

Configuring VS Code to auto-fix ESLint violations on save creates a seamless experience where style issues are fixed automatically without developer intervention.

Pre-commit Hooks with husky

While IDE integration catches issues during development, some teams add an additional safety net through pre-commit hooks. Tools like husky can run ESLint before code is committed, preventing violations from entering the repository even if a developer has disabled editor integration.

# Example pre-commit hook
npx eslint --cache --cache-location .eslintcache $(git diff --cached --name-only | grep '\.js$')

Pre-commit hooks should be configured to only lint staged files for better performance on large projects. The cache flag is important, as it allows ESLint to skip re-linting files that haven't changed.

Enhance your development workflow further by understanding the History API for building single-page applications with proper browser history management.

CI/CD Integration and Continuous Quality

Integrating ESLint into your continuous integration pipeline ensures that all code meets your quality standards before it's merged or deployed. This automated checking provides a safety net that catches violations even when developers forget to run checks locally, as recommended in the ESLint documentation.

GitHub Actions Workflow

Most CI systems can run ESLint with minimal configuration. The key is ensuring the pipeline has access to your project's dependencies and uses the same configuration as local development:

- name: Run ESLint
 run: npm run lint
 env:
 CI: true

This assumes you have a lint script in your package.json that runs ESLint. The script might simply be "lint": "eslint ." or might include additional options like --cache for improved performance on subsequent runs.

Using ESLint as a Quality Gate

For teams that want strict enforcement, ESLint can be configured to fail builds when violations are found. When using ESLint as a quality gate, consider which rules should block builds versus which should only generate warnings:

// In package.json
{
 "scripts": {
 "lint": "eslint . --max-warnings=0"
 }
}

Error-level violations typically block builds, while warnings may be reported but not fail the pipeline. This distinction allows teams to enforce critical standards while remaining flexible about style preferences.

The Plugin Ecosystem

The ESLint plugin ecosystem extends the core tool with specialized rules for frameworks, best practices, and specific use cases, as outlined in the LogRocket ESLint adoption guide.

Essential Plugins

Framework-Specific Configuration

For React projects, the eslint-plugin-react package provides rules specific to React patterns:

npm install --save-dev eslint-plugin-react

export default tseslint.config(
 ...tseslint.configs.recommended,
 {
 plugins: {
 react: reactPlugin,
 },
 rules: {
 "react/jsx-no-undef": "error",
 },
 },
);

Security-focused plugins like eslint-plugin-security check for vulnerable patterns such as eval usage, while accessibility plugins like jsx-a11y help ensure your code is accessible to users with disabilities.

Conclusion: Building a Sustainable Quality Culture

Successful ESLint adoption is a journey, not a destination. The most effective teams view ESLint as a living part of their development process, continuously refining configurations as their codebase and practices evolve, as emphasized in the LogRocket ESLint adoption guide.

The investment in proper ESLint adoption pays dividends throughout a project's lifecycle: developers spend less time on style discussions in code reviews, bugs are caught earlier in the development process, and new team members onboard faster when code follows consistent patterns.

Remember that ESLint is a tool to help developers, not to create frustration. The best configurations balance thoroughness with practicality, catching important issues while not overwhelming teams with minor violations. Start with established configurations like those from typescript-eslint, add rules incrementally, and maintain configuration consistency across projects.

As your team grows and your codebase evolves, revisit your ESLint configuration to ensure it continues to serve its purpose of maintaining code quality and consistency. Our web development services include code quality audits and tooling setup to help teams establish sustainable development practices.

Sources

1. ESLint: Getting Started - Official ESLint documentation covering quick start, manual setup, configuration files, and CLI options for ESLint 9+
2. typescript-eslint: Getting Started - Official TypeScript ESLint quickstart guide with step-by-step installation and configuration
3. LogRocket: ESLint adoption guide - Comprehensive guide covering ESLint basics, configuration options, plugins, and team adoption strategies