Skip to content

Philosophy

eslint-plugin-code-style exists because consistent code formatting goes beyond what ESLint's built-in rules cover. Here are the principles that guide every rule in the plugin.

Filling the Gaps

Base formatters handle whitespace: indentation, semicolons, trailing commas, line width. They deliberately avoid opinions on structural patterns. ESLint's built-in rules and most plugins focus on catching bugs and enforcing best practices, not formatting style. This plugin fills what they leave behind.

It covers the structural consistency no other tool enforces: how array items break across lines, how JSX children are formatted, arrow function bodies, and dozens more. This is the formatting that base formatters and logic-focused linters leave alone.

Self-Sufficient Rules

Every rule is self-contained. No rule depends on another rule to work correctly. You can enable any single rule in isolation and get the expected behavior without surprises.

This also means rules do not conflict with each other. Enabling the entire plugin produces a consistent output with no contradictory fixes.

Auto-Fix First

72 of 83 rules are auto-fixable. The goal is to let developers write code naturally and then run eslint --fix to apply formatting automatically. This reduces the cognitive overhead of remembering style rules and eliminates back-and-forth in code reviews over formatting issues.

The remaining 11 rules are report-only because their fixes would be ambiguous or could change runtime behavior. In those cases, the rule reports the issue and lets the developer decide how to resolve it.

Consistency at Scale

On a team, small formatting differences compound quickly. One developer puts array items on one line, another breaks them across lines. One uses implicit arrow returns, another always uses block bodies. These inconsistencies make a codebase read as if ten different people wrote it.

These rules enforce a single way to format each pattern. The result is a codebase that reads as if one person wrote it, regardless of team size.

Opinionated but Configurable

The plugin ships with sensible defaults that work well for most projects. But 24 of the 83 rules accept configuration options for cases where the defaults do not fit. For example:

  • array-items-per-line defaults to collapsing arrays with 3 or fewer items, but you can adjust the threshold.
  • hook-deps-per-line defaults to expanding dependency arrays with more than 3 dependencies, but you can set a different limit.
  • use-state-naming-convention allows you to extend the list of valid boolean prefixes beyond the defaults.

Defaults are chosen to match what the majority of React codebases already do. Configuration options exist for the minority that need something different.

Naming Conventions

Several rules enforce naming conventions for variables, functions, hooks, components, and files. These rules exist because consistent naming is one of the highest-leverage ways to improve codebase readability.

When you see a function named useAuth, you immediately know it is a React hook. When you see a file named use-auth.ts, you know it contains a hook. When a boolean prop starts with is or has, you know its type without checking. These conventions eliminate guesswork.

Type-Based Folder Structure

The plugin is designed around a type-based folder structure — source files grouped by their role rather than by feature: components, atoms, views, pages, hooks, providers, services, middlewares, constants, data, and so on. Several rules read the folder a file lives in and build their expectations from it.

folder-based-naming-convention applies the right suffix per folder (views become *View, pages become *Page, providers become *Provider), folder-structure-consistency and no-redundant-folder-suffix keep module folders tidy, and the index, hook, function, and variable naming rules are path-scoped to this layout. The closer your project follows it, the more the plugin enforces and auto-fixes for you; rules that do not depend on folders (spacing, JSX, imports, formatting) work the same in any layout.

React First

This plugin is purpose-built for React and JSX projects. Many rules target patterns that only exist in React codebases: component prop destructuring, hook dependency arrays, JSX ternary formatting, className ordering, and more.

General-purpose JavaScript rules (arrays, objects, functions, control flow) are included because they affect how React code reads and are not covered by other tools.

Works Alongside Existing Tools

The plugin is designed to work alongside eslint-plugin-react, @typescript-eslint, and any other ESLint plugins you use. It does not duplicate their rules or conflict with their fixes.

Run your formatter for base whitespace, this plugin for structural formatting, and your existing plugins for logic and best practices. They complement each other.

Next Steps