magento / magento/magento-coding-standard
ESLint 9: `npm run eslint` fails when used as vendor dependency due to strict base path enforcement
- 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
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