eslint-plugin-paths

1.1.0 verified Sat Apr 25 auth: no javascript

ESLint plugin that enforces the use of path aliases defined in tsconfig.json or jsconfig.json instead of relative imports. Version 1.1.0 is the latest stable release, with active development. Unlike alternatives that introduce their own alias configuration, this plugin reads directly from TypeScript/JavaScript config files, providing a single source of truth. Supports auto-fix via eslint --fix. Designed for zero-config, plug-and-play usage. Requires ESLint and Node.js.

Common errors

error Configuration for rule "paths/alias" is invalid: Value "error" for key "severity" should be a number or string. ↓

cause Incorrect rule configuration syntax.

fix

Use: "paths/alias": "error" or "paths/alias": ["error", options] in ESLint config.

error Definition for rule 'paths/alias' was not found. ↓

cause Plugin not added to ESLint plugins array.

fix

Add "eslint-plugin-paths" to the plugins section in ESLint config.

error Cannot find module 'eslint-plugin-paths' ↓

cause Plugin not installed or wrong package name.

fix

Run: npm install -D eslint-plugin-paths

error Unable to resolve path to tsconfig.json ↓

cause tsconfig.json not found in working directory or custom path wrong.

fix

Create tsconfig.json or set configFilePath option with absolute/relative path.

Warnings

gotcha Plugin reads only tsconfig.json or jsconfig.json; custom aliases in other files are ignored. ↓

fix Ensure your aliases are defined in a compatible config file or use configFilePath option.

gotcha The rule does not check for unused aliases; it only enforces alias usage when possible. ↓

fix Manually review tsconfig paths to avoid unused aliases.

gotcha Auto-fix may change import paths to aliases even when relative path is intended; no ignore annotation support. ↓

fix Disable auto-fix for specific files or paths with ESLint comment or ignore patterns.

gotcha Plugin does not support multiple config files out of the box; configFilePath accepts a single file. ↓

fix If multiple configs needed, consider extending the plugin or using a preprocessor.

Install

npm install eslint-plugin-paths

yarn add eslint-plugin-paths

pnpm add eslint-plugin-paths

Imports

plugin

wrong

const paths = require('eslint-plugin-paths')

correct

import paths from 'eslint-plugin-paths'

Default import is used; plugin is ESM-compatible.

rule alias
wrong
```
'plugins/paths/alias': 'error'
```
correct
```
'paths/alias': 'error'
```
Rules are namespaced under 'paths/' prefix.

config

wrong

"paths/alias": ["error", { "configFilePath": "tsconfig.json" }]

correct

"paths/alias": ["error", { "config": "tsconfig.json" }]

Option name is 'config', not 'configFilePath' in v1.1.0.

Quickstart

Install plugin, configure ESLint, set up tsconfig paths, and run ESLint to enforce alias usage.

npm install -D eslint-plugin-paths

echo '{
  "plugins": ["eslint-plugin-paths"],
  "rules": {
    "paths/alias": "error"
  }
}' > .eslintrc.json

# tsconfig.json example
echo '{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}' > tsconfig.json

# Invalid: relative import
echo 'import foo from "./foo"' > src/index.ts

# Run ESLint
npx eslint src/index.ts --fix