@dword-design/eslint-plugin-import-alias

An ESLint plugin that enforces the use of import aliases. Also supports autofixing.

Aliases are a great thing to make imports more readable and you do not have to change import paths that often when a file path is changed.

import foo from '../../model/sub/foo';
import bar from '../other/bar';

changes to

import foo from '@/model/sub/foo';
import bar from '@/sub/other/bar';

Now what if you are in a bigger team or you have a lot of projects to update. Or you just want to make sure that everything is consistent. This is where a linter comes into the play. This rule allows you to detect inconsistent imports and even autofix them. This works by matching alias paths agains the imports and replacing the import paths with the first matching aliased path.

Install

# npm
$ npm install @dword-design/eslint-plugin-import-alias

# Yarn
$ yarn add @dword-design/eslint-plugin-import-alias

Usage

Add the plugin to your ESLint config:

// eslint.config.ts

import { defineConfig } from 'eslint/config';
import importAlias from '@dword-design/import-alias';

export default defineConfig([
  importAlias.configs.recommended,
]);

Options can be passed by setting them in the prefer-alias rule:

// eslint.config.ts

import { defineConfig } from 'eslint/config';
import importAlias from '@dword-design/import-alias';

export default defineConfig([
  importAlias.configs.recommended,
  {
    rules: {
      '@dword-design/import-alias/prefer-alias': ['error', /* options */],
    },
  },
]);

Now you have multiple ways to tell the plugin about aliases.

tsconfig.json paths setting

If you are a TypeScript user and you have aliases configured in your tsconfig.json via the paths setting, they will automatically be loaded. You can disable this behavior by setting shouldReadTsConfig to false in the plugin options.

babel-plugin-module-resolver

If you are already using babel-plugin-module-resolver, the plugin will load the Babel config and extract the alias and resolvePath options. You can disable this behavior by setting shouldReadBabelConfig to false in the plugin options.

// .babelrc.json

{
  "plugins": {
    ["module-resolver", {
      "alias": {
        "@": ".",
      },
    }]
  }
}

Plugin alias option

You can also just pass the aliases to the plugin as an option.

// eslint.config.ts

import { defineConfig } from 'eslint/config';
import importAlias from '@dword-design/import-alias';

export default defineConfig([
  importAlias.configs.recommended,
  {
    rules: {
      '@dword-design/import-alias/prefer-alias': [
        'error',
        {
          'alias': {
            '@': './src',
            '@components': './src/components',
          },
        },
      ],
    },
  },
]);

Alias resolution

By default, the plugin will convert parent paths to aliases (like ../model/foo), but will keep subpath imports relative. You can change that to also convert subpaths to aliased imports by passing the aliasForSubpaths option to the rule like so:

rules: {
  '@dword-design/import-alias/prefer-alias': ['error', { aliasForSubpaths: true }],
}

Also, inner alias paths are preferred to outer ones. Example:

rules: {
  '@dword-design/import-alias/prefer-alias': ['error', { alias: { '@': './app', '@@': '.' }],
}

If an import resolves to a file insode app, @ will be preferred over @@ although both aliases match. This is convenient for the use case where you have a lot of aliases for top-level folders like components, utils etc where you usually want those instead of a generic root alias. If you have other use cases, please let me know.

Contribute

Are you missing something or want to contribute? Feel free to file an issue or a pull request! ⚙️

Support

Hey, I am Sebastian Landwehr, a freelance web developer, and I love developing web apps and open source packages. If you want to support me so that I can keep packages up to date and build more helpful tools, you can donate here:

Thanks a lot for your support! ❤️

License

MIT License © Sebastian Landwehr