eslint-plugin-no-relative-import

ESLint plugin to replace relative imports (./, ../) with TypeScript path aliases from the nearest tsconfig.json.

What it does

Transforms relative imports into clean, maintainable path aliases:

// Before
import { helper } from "../../../utils/helper";
import { Button } from "../components/Button";

// After (auto-fix)
import { helper } from "@/utils/helper";
import { Button } from "@/components/Button";

Features

• Auto-fixable — run eslint --fix to convert all relative imports automatically
• tsconfig-aware — reads compilerOptions.paths and baseUrl from the nearest tsconfig.json
• Extends support — resolves extends chains in tsconfig
• Monorepo-friendly — each package uses its own tsconfig
• Manual aliases — works without tsconfig via rule options
• Granular control — allowlist, ignore patterns, sibling import toggle

Supported import types

• import { x } from "../thing"
• export { x } from "../thing"
• export * from "../thing"
• await import("../thing")
• require("../thing")

Installation

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

Usage

ESLint Flat Config (v9+)

// eslint.config.js
import noRelativeImport from "eslint-plugin-no-relative-import";

export default [
  {
    plugins: {
      "no-relative-import": noRelativeImport,
    },
    rules: {
      "no-relative-import/no-relative-import": "error",
    },
  },
];

ESLint Legacy Config (v8)

// .eslintrc.js
module.exports = {
  plugins: ["no-relative-import"],
  rules: {
    "no-relative-import/no-relative-import": "error",
  },
};

Recommended preset

// eslint.config.js
import noRelativeImport from "eslint-plugin-no-relative-import";

export default [
  noRelativeImport.configs.recommended,
];

Oxlint

Oxlint supports ESLint v9+ compatible plugins via jsPlugins. Add to .oxlintrc.json:

{
  "jsPlugins": ["eslint-plugin-no-relative-import"],
  "rules": {
    "no-relative-import/no-relative-import": "error"
  }
}

The plugin must be installed in your project (npm install --save-dev eslint-plugin-no-relative-import). Oxlint resolves the plugin name relative to the config file.

Note: jsPlugins support is alpha in Oxlint. The plugins field is for native Oxlint plugins only — ESLint plugins go in jsPlugins.

Configuration

Rule options

"no-relative-import/no-relative-import": ["error", {
  // Manual aliases (when no tsconfig or to augment it)
  alias: {
    "@/*": "./src/*",
    "@components/*": "./src/components/*",
  },

  // Relative paths that are allowed (supports * wildcard)
  allowRelative: ["./styles.css", "../assets/*"],

  // Whether to convert sibling imports like "./foo". Default: true
  includeSiblingImports: false,

  // Import paths to ignore entirely (supports * wildcard)
  ignorePatterns: ["*.css", "*.graphql"],

  // Override working directory for tsconfig lookup and alias resolution
  cwd: "/path/to/project",
}]

Example: disable sibling imports

Keep ./ imports for co-located files, only fix ../:

rules: {
  "no-relative-import/no-relative-import": ["error", {
    includeSiblingImports: false,
  }],
}

Example: allow specific patterns

rules: {
  "no-relative-import/no-relative-import": ["error", {
    allowRelative: ["./styles", "../types/*"],
  }],
}

Example: manual aliases without tsconfig

rules: {
  "no-relative-import/no-relative-import": ["error", {
    alias: {
      "@": "./src",
      "@lib/*": "./lib/*",
    },
  }],
}

How it works

1. Finds the nearest tsconfig.json for each linted file
2. Reads compilerOptions.paths and compilerOptions.baseUrl
3. Resolves extends chains in tsconfig
4. When a relative import can be replaced by a path alias, reports it with an auto-fix
5. Picks the most specific alias when multiple match

tsconfig example

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

Requirements

• Node.js 18+
• ESLint 8.57+ or 9+
• TypeScript project (for automatic tsconfig discovery)

License

MIT