eslint-plugin-preferred-import

1.1.1 verified Fri May 01 auth: no javascript

ESLint plugin that autofixes relative imports to use TypeScript or JavaScript path aliases. Current stable version is 1.1.1. Released with moderate cadence; supports both ESLint 9 flat config (with typescript-eslint) and legacy ESLint 8 config. Key differentiator: auto-fixable rules that replace relative paths with configured aliases from tsconfig.json (ts-imports) or manual webpack-like alias map (js-imports), rather than just reporting violations. Requires Node >=16 and ships TypeScript types.

Common errors

error Failed to load plugin 'preferred-import' declared in 'plugins': Cannot find module 'eslint-plugin-preferred-import' ↓

cause Plugin not installed in the project's node_modules.

fix

Run npm install eslint-plugin-preferred-import --save-dev.

error Definition for rule 'preferred-import/ts-imports' was not found ↓

cause Rule name is misspelled or plugin not registered correctly in eslint config.

fix

Ensure plugin is imported and registered under the key 'preferred-import' (exact string); rules must be 'preferred-import/ts-imports'.

error Configuration for rule 'preferred-import/ts-imports' is invalid: Value "error" should be a number or an array. ↓

cause Using flat config with string severity instead of severity level from @eslint/js.

fix

Use 'error' (string) is allowed? Actually ESLint flat config accepts string; if using @eslint/js, may need to use 'error' or 2. Check ESLint version.

error Parsing error: parserOptions.project has been deprecated; use projectService instead ↓

cause Using older parserOptions.project in typescript-eslint v8+.

fix

Replace parserOptions.project with parserOptions.projectService: true in flat config.

Warnings

gotcha ts-imports rule requires TypeScript project with tsconfig.json containing basePath and paths. ↓

fix Ensure tsconfig has basePath and paths configured; provide project or projectService in parserOptions.

gotcha Rule does not correct incorrect import paths, only replaces relative paths with alias paths if alias maps correctly. ↓

fix Verify that the alias resolves to the actual file; if not, the import will be incorrect after autofix.

breaking ESLint 9 requires flat config; plugin v1.1.1 works with both but config format differs significantly. ↓

fix For ESLint 9, use the flat config import and plugins object; for ESLint 8, use plugins array and overrides.

Install

npm install eslint-plugin-preferred-import

yarn add eslint-plugin-preferred-import

pnpm add eslint-plugin-preferred-import

Imports

default (import preferredImport)

wrong

import * as preferredImport from 'eslint-plugin-preferred-import'

correct

import preferredImport from 'eslint-plugin-preferred-import'

Default export is an object containing rules; named exports are not available.

plugin in flat config
wrong
```
plugins: { preferredImport }
```
correct
```
plugins: { 'preferred-import': preferredImport }
```
Plugin name must be the string 'preferred-import' as used in rule names (e.g., preferred-import/ts-imports).
rule ts-imports
wrong
```
rules: { 'ts-imports': 'error' }
```
correct
```
rules: { 'preferred-import/ts-imports': 'error' }
```
Rules are namespaced under 'preferred-import/'; omitting prefix causes the rule to not be found.
require in CommonJS
wrong
```
const { ts-imports } = require('eslint-plugin-preferred-import')
```
correct
```
const preferredImport = require('eslint-plugin-preferred-import')
```
Require returns the full plugin object; individual rules must be accessed via preferredImport.rules['ts-imports'].

Quickstart

Flat ESLint 9 configuration enabling ts-imports rule to autofix relative imports to tsconfig aliases.

// eslint.config.mjs
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import preferredImport from 'eslint-plugin-preferred-import';

export default tseslint.config(
  eslint.configs.recommended,
  tseslint.configs.recommendedTypeChecked,
  {
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      parserOptions: {
        projectService: true,
      },
    },
    plugins: { 'preferred-import': preferredImport },
    rules: {
      'preferred-import/ts-imports': 'error',
    },
  },
  { ignores: ['**/node_modules/**', '**/dist/**', '**/.next/**', '**/.turbo/**'] },
);