eslint-plugin-no-relative-import-paths

1.6.1 verified Sat Apr 25 auth: no javascript

ESLint plugin that enforces absolute import paths, preventing the need to update imports when moving files between folders. Version 1.6.1 supports both legacy ESLint config (.eslintrc) and flat config (eslint.config.js), includes TypeScript types, and offers auto-fix via --fix. Options include allowSameFolder, rootDir, prefix, and allowedDepth for flexible configuration. Unlike similar rules (e.g., import/no-relative-parent-imports), this plugin focuses solely on prohibiting relative imports with fix support.

Common errors

error ESLint: Failed to load plugin 'no-relative-import-paths' due to an error: Cannot find module 'eslint-plugin-no-relative-import-paths' ↓

cause Plugin not installed or ESLint cannot resolve it.

fix

Run npm install eslint-plugin-no-relative-import-paths --save-dev

error ESLint: Configuration for rule 'no-relative-import-paths/no-relative-import-paths' is invalid: Value "off" is not a valid severity ↓

cause Using 'off' as a string instead of 0 in legacy config, or mixing flat/legacy patterns.

fix

Use 0 (off), 1 (warn), or 2 (error) as numeric values in legacy config, or 'off'/'warn'/'error' in flat config consistently.

error Parsing error: The keyword 'import' is reserved ↓

cause ESLint not configured for ES modules; using import/export without parserOptions.sourceType: 'module'.

fix

In legacy config: add "parserOptions": { "sourceType": "module" }. In flat config, set languageOptions: { sourceType: 'module' }.

error TypeError: Cannot read properties of undefined (reading 'allowSameFolder') ↓

cause Options object is undefined in older versions (before v1.3.4). The rule expects an options object even if empty.

fix

Update plugin to v1.3.4+: npm install eslint-plugin-no-relative-import-paths@1.3.4

error ESLint: Flat config: plugins[n] must be a string or object, got array ↓

cause Using an array of plugin strings in flat config instead of an object mapping plugin name to plugin object.

fix

Use plugins: { 'no-relative-import-paths': pluginObject } (not an array).

Warnings

breaking Flat config support requires plugin version >=1.5.4 and ESLint >=9.0.0-0. Using older plugin version with flat config will not work. ↓

fix Update to eslint-plugin-no-relative-import-paths@1.5.4 or newer: npm install eslint-plugin-no-relative-import-paths@latest

breaking The rule is not enabled by default; you must explicitly configure it. Setting the rule to 'off' (0) will disable it entirely. ↓

fix Set the rule to 'warn' or 'error' in your ESLint config (or 1 or 2 in legacy config).

deprecated The options 'enabled' and 'ignorePureComponents' are not documented in recent versions. 'enabled' is replaced by the standard ESLint severity; 'ignorePureComponents' is likely a mistake (confused with allowSameFolder). ↓

fix Use severity level (0/1/2) instead of 'enabled'. Use 'allowSameFolder' instead of 'ignorePureComponents'.

gotcha The auto-fix may add the rootDir as a prefix if rootDir is not set, e.g., fixing '../../components' to 'src/components' instead of 'components'. ↓

fix Set rootDir option to strip the root directory from the absolute path, e.g., { rootDir: 'src' }.

breaking In v1.5.2 and earlier, the prefix option was added but could produce paths with duplicate slashes if rootDir was also set. Now properly handled. ↓

fix Update to v1.5.3 or newer: npm install eslint-plugin-no-relative-import-paths@1.5.3

gotcha The rule checks all import/export statements including dynamic imports. Relative imports in require() calls are also flagged. ↓

fix To allow dynamic or require imports, consider using the 'allowedDepth' option or disable the rule selectively.

breaking TypeScript types were added in v1.6.0. Using type definitions with older versions may cause TypeScript errors or missing types. ↓

fix Upgrade to v1.6.0 or newer, or manually define types if needed.

Install

npm install eslint-plugin-no-relative-import-paths

yarn add eslint-plugin-no-relative-import-paths

pnpm add eslint-plugin-no-relative-import-paths

Imports

default export

wrong

const noRelativeImportPaths = require('eslint-plugin-no-relative-import-paths')

correct

import noRelativeImportPaths from 'eslint-plugin-no-relative-import-paths'

For flat config (ESLint >=9), use default import. For legacy config, use plugins array with string 'no-relative-import-paths'.

rule 'no-relative-import-paths'
wrong
```
rules: { 'no-relative-import-paths': 'warn' }
```
correct
```
rules: { 'no-relative-import-paths/no-relative-import-paths': 'warn' }
```
Rule is namespaced under the plugin. Must include 'no-relative-import-paths/' prefix.

flat config usage

wrong

export default [{ plugins: ['no-relative-import-paths'], rules: { 'no-relative-import-paths/no-relative-import-paths': 'error' } }]

correct

import plugin from 'eslint-plugin-no-relative-import-paths'; export default [{ plugins: { 'no-relative-import-paths': plugin }, rules: { 'no-relative-import-paths/no-relative-import-paths': 'error' } }]

Flat config requires plugin object, not string. Available since v1.5.4.

Quickstart

Shows flat config and legacy config setup for the plugin with common options: allowSameFolder, rootDir, and prefix.

// eslint.config.js (ESLint flat config, requires v1.5.4+)
import noRelativeImportPaths from 'eslint-plugin-no-relative-import-paths';

export default [
  {
    plugins: {
      'no-relative-import-paths': noRelativeImportPaths,
    },
    rules: {
      'no-relative-import-paths/no-relative-import-paths': [
        'error',
        { allowSameFolder: true, rootDir: 'src', prefix: '@' }
      ]
    }
  }
];

// .eslintrc.json (legacy config)
// {
//   "plugins": ["no-relative-import-paths"],
//   "rules": {
//     "no-relative-import-paths/no-relative-import-paths": [
//       "warn",
//       { "allowSameFolder": true, "rootDir": "src", "prefix": "@" }
//     ]
//   }
// }