magento / magento/magento-coding-standard

ESLint 9: `npm run eslint` fails when used as vendor dependency due to strict base path enforcement

Open Beginner friendly
#501 1 comment 1 reaction 0 assignees View on GitHub
bug
Dominant language
PHP
Stars
375
Forks
165
PR merge metrics
No merged PRs in 30d

Description

## Description
After upgrading to a version of magento-coding-standard that uses ESLint 9,
the documented `npm run eslint -- path/to/analyze` command no longer works
when the package is installed as a vendor dependency via composer.

## Root Cause
ESLint 9 introduced strict base path enforcement (flat config) - ESLint 9
sets its base path to the physical location of `eslint.config.mjs`. It
refuses to lint any files outside that folder.

Since `eslint.config.mjs` physically lives at:
`vendor/magento/magento-coding-standard/eslint/eslint.config.mjs`

And project files are at:
`app/code/` or `app/design/`

ESLint refuses to lint them because they are outside the base path.

## What Worked

### 1. Running the binary directly from project root
Instead of `npm run eslint`, run the binary directly from `src/`:
```bash
vendor/magento/magento-coding-standard/node_modules/.bin/eslint \
-c vendor/magento/magento-coding-standard/eslint/eslint.config.mjs \
app/code/
```

Running from `src/` sets the working directory correctly so ESLint's base
path covers both `app/code/` and `app/design/` directories.

### 2. Handling ignore paths
Since ESLint 9 also removed support for `.eslintignore`, a wrapper
`eslint.config.mjs` was created at the project root (`src/`) to import
the magento config and add project specific ignore patterns:
```js
import magentoConfig from "./vendor/magento/magento-coding-standard/eslint/eslint.config.mjs";

export default [
...magentoConfig,
{
ignores: [
// add your project specific ignore patterns here
'**/path/to/file-to-ignore.js',
],
}
];
```

This wrapper config at `src/` level also allows running ESLint without
the `-c` flag, since ESLint will automatically find and use it by searching
upward from the target files:
```bash
vendor/magento/magento-coding-standard/node_modules/.bin/eslint app/code/
```

## Suggested Fix
Update the README to document the correct usage for projects that install
this as a vendor dependency, including:
1. Running the binary directly from the project root
2. Creating a wrapper `eslint.config.mjs` at project root level for ignore patterns

Contributor guide

Open the contributing guide

Research direction

Start with the README and the documented `npm run eslint -- path/to/analyze` command. Compare it with the vendor binary invocation and the project-root `eslint.config.mjs` wrapper described in the issue. Done means the README explains both the project-root command and adding project-specific ignore patterns for vendor installs.

Written by the indexing model from the issue text.

Assessment

Tech stack
eslint
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
74/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.