> ## Documentation Index
> Fetch the complete documentation index at: https://isox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# ESLint executor

> Lint project files, apply fixes, and enforce warning limits with eslint:lint.

## Install

Requires Node.js 24 or 26+. Install the plugin in your workspace:

```sh theme={null}
npm install --save-dev @isox-sh/eslint
```

The plugin includes ESLint. Keep your ESLint configuration and any parsers or
rule plugins installed in the workspace.

If your `eslint.config.mjs` imports `eslint/config`, install `eslint` directly too
so that import resolves with package managers that isolate dependencies.

## Define a lint command

Add a lint target to an existing project:

```sh theme={null}
isox add @isox-sh/eslint my-app
```

The generator preserves existing ESLint targets and rejects conflicting lint
targets. It is also called by `isox init @isox-sh/js` unless `--linter=none` is set.
If there is no root ESLint config, it creates `eslint.config.mjs` with recommended
JavaScript and TypeScript rules, Node.js globals, and ignores for build output,
coverage, and Isox state. The root `package.json` gets dev dependencies for
`@isox-sh/eslint`, `eslint`, `@eslint/js`, `typescript-eslint`, `typescript`, and
`globals`. Run your package manager's install command before linting.

Existing configs are preserved, including JavaScript, TypeScript, and legacy
formats; existing dependency versions and dependency classifications are retained.
When a config already exists, only the executor plugin and ESLint dependencies
are ensured. Legacy configs produce a migration warning because ESLint 10 uses
flat config. Running `add` again also repairs missing workspace setup when a
lint target already exists.

```json theme={null}
{
  "name": "my-app",
  "targets": {
    "lint": {
      "executor": "eslint:lint",
      "options": {
        "maxWarnings": 0
      }
    }
  }
}
```

Run `isox lint my-app`. The fully scoped executor name is
`@isox-sh/eslint:lint`.

Apply automatic fixes from the CLI:

```sh theme={null}
isox lint my-app --fix
isox run my-app:lint --fix
isox run-many --target=lint --fix
isox affected --target=lint --fix
```

The CLI flag overrides `fix` from the target's options or selected configuration.
Other plugin options work the same way, such as `--max-warnings=5` or
`--config-file=eslint.custom.mjs`; the CLI forwards unrecognized flags to the executor.
For multi-project runs, it applies to the requested target, leaving pre/post
targets' options unchanged. Use `--no-fix` to disable configured fixes for a run.

## Options

| Option | Default | Description |
| - | - | - |
| `lintFilePatterns` | Project root | Non-empty array of files, directories, or globs relative to the workspace root. Absolute paths are also accepted. |
| `configFile` | ESLint discovery | Configuration path relative to the workspace root, or absolute. |
| `fix` | `false` | Apply ESLint's automatic fixes. |
| `maxWarnings` | `0` | Maximum allowed warnings; `-1` allows unlimited warnings. |

ESLint runs from the workspace root, and default linting selects only the current
project. Globs are passed directly to ESLint without shell expansion. Lint errors,
excess warnings, unmatched patterns, and configuration failures fail the command.
Cancellation stops the child process through Isox's shared process runner.

## Cache lint results

Add workspace defaults in `isox.json` to cache successful lint results and terminal
output without declaring any build artifacts:

```json theme={null}
{
  "targetDefaults": {
    "eslint:lint": {
      "cache": true,
      "inputs": ["{projectRoot}/**/*", "{workspaceRoot}/eslint.config.*"]
    }
  }
}
```

Include any imported configuration helpers, custom `configFile`, or additional
`lintFilePatterns` outside the project in `inputs` too. When `--fix` changes an
input file, that run is not cached. Source edits are never restored as artifacts.
Use `--skip-cache` to force linting. See [local task caching](https://isox.sh/docs/task-caching.md).

For array-valued options, use JSON to preserve the array even with one pattern:

```sh theme={null}
isox lint my-app --options '{"lintFilePatterns":["apps/my-app/src/**/*.ts"]}'
```

These options use the corresponding [ESLint CLI options](https://eslint.org/docs/latest/use/command-line-interface).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.