eslint-plugin-shortest-import

ESLint plugin to prefer the shortest import path, automatically choosing between relative imports and TypeScript path aliases based on which one results in fewer path segments.

Installation

npm install @marqhq/eslint-plugin-shortest-import --save-dev

Usage

ESLint Flat Config (eslint.config.js)

import shortestImport from "@marqhq/eslint-plugin-shortest-import";

export default [
  {
    plugins: {
      "@marqhq/shortest-import": shortestImport,
    },
    rules: {
      "@marqhq/shortest-import/shortest-import": "warn",
    },
  },
];

Legacy ESLint Config (.eslintrc)

{
  "plugins": ["@marqhq/shortest-import"],
  "rules": {
    "@marqhq/shortest-import/shortest-import": "warn"
  }
}

Rule Options

"@marqhq/shortest-import/shortest-import": ["warn", {
  "tsconfigPath": "./tsconfig.json", // Optional: path to tsconfig.json
  "preferOnTie": "alias" // Optional: "alias" | "relative" | "keep" (default: "keep")
}]

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | tsconfigPath | string | ./tsconfig.json | Path to your tsconfig.json file | | preferOnTie | "alias" | "relative" | "keep" | "keep" | What to prefer when segment counts are equal |

• "alias" - On tie, convert to the tsconfig path alias
• "relative" - On tie, convert to the relative import
• "keep" - On tie, keep the current import style (default)

How It Works

The rule compares the "segment count" of import paths:

• ./Button = 1 segment
• ../utils/helpers = 3 segments (.., utils, helpers)
• @components/Button = 2 segments (@components, Button)
• @/components/Button = 3 segments (@, components, Button)

The rule suggests switching to whichever form has fewer segments.

Examples

Given this tsconfig.json:

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

Relative to Alias (when alias is shorter)

// File: src/features/auth/login.ts

// Bad - 4 segments
import { Button } from "../../components/Button";

// Good - 2 segments
import { Button } from "@components/Button";

Alias to Relative (when relative is shorter)

// File: src/components/App.ts

// Bad - 3 segments
import { Button } from "@/components/Button";

// Good - 1 segment
import { Button } from "./Button";

Auto-fix

This rule supports ESLint's --fix option to automatically convert imports to the shorter form.

eslint --fix src/

Requirements

• ESLint >= 8.0.0
• TypeScript >= 4.0.0
• A tsconfig.json with paths configured

Development

Setup

npm install
npm run build
npm test

Releasing

To publish a new version:

1. Update the version in package.json
2. Commit the change: git commit -am "Bump version to x.x.x"
3. Create and push a tag: git tag vx.x.x && git push origin vx.x.x
4. Create a GitHub release: gh release create vx.x.x --title "vx.x.x" --notes "Release notes here"

The GitHub Action will automatically build, test, and publish to GitHub Packages.

License

MIT