📖 Description

ESLint Plugin that includes rules which encourage the use of absolute paths over relative paths, defined by paths or baseUrl from tsconfig.json

🗂️ Summary

• Installation
• Requirements
• Usage
  • Recommended configuration
  • Configure the Rules
  • TSConfig.json
  • Node Absolute Paths
• Frameworks
  • TypeScript (tsc)
  • Vite / Vitest
  • Next.js
  • Gatsby - soon
  • Webpack - soon
• Rules
  • absolute-import
  • absolute-export
  • absolute-parent-import
  • absolute-parent-export

🎒 Installation

In your terminal, run the command below:

npm i -D eslint-plugin-typescript-paths

🧩 Requirements

Considering we're talking about a plugin for TypeScript, it's crucial to configure the @typescript-eslint plugin first. While the eslint-plugin-import and eslint-import-resolver-typescript plugins are not obligatory, they provide a more consistent approach to module resolution and are recommended for usage.

As an alternative approach to the above-mentioned setups, you can consider using a Kiskadee ESLint Configuration at any level, which not only covers all the prerequisite configurations but also offers support for this plugin.

🪁 Usage

✧ Recommended Configuration

To use the recommended rules, in the .eslintrc (or equivalent) file, extend plugin:typescript-paths/recommended.

  module.exports = {
    extends: ['plugin:typescript-paths/recommended'],
    rules: {
      // your rules
    },
  };

✧ Configure the Rules

Define typescript-paths plugin in the .eslintrc (or equivalent) file.

  module.exports = {
    plugins: ['typescript-paths'],
    rules: {
      // your rules
    },
  };

✧ TSConfig.json

Your project requires a tsconfig.json. Despite the plugin's capability to function without specified paths or a baseUrl in the tsconfig.json, we utilize the default baseUrl, "./". This allows us to provide suggestions for absolute paths, or not, as needed. However, without a tsconfig.json file, the plugin simply won't operate.

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./",
      "paths": [{
        "app/*": ["./src/app/*"],
        "config/*": ["./src/app/_config/*"],
        "environment/*": ["./src/environments/*"],
        "shared/*": ["./src/app/_shared/*"],
        "helpers/*": ["./src/helpers/*"],
        "tests/*": ["./src/tests/*"],
        "@/*": ["./src/*"],
      }]
    }
  }

Keep in mind that the ./ origin used in paths is relative to the baseUrl. Using the above example as reference, it would be possible to set baseUrl as ./src, and paths as "app/*": ["./app/*"].

✧ Node Absolute Paths

Node.js interprets absolute imports based on the location of the file being executed. That is, if you start an import with /, it will consider the root of the filesystem as the starting point. This can be confusing, as in many other environments, such as the web and some JavaScript transpilers like Babel, an import starting with / refers to the root of the project.

❌ Not Recommended

  import logo from '/img/logo.svg';
  import Helvetica from '/fonts/Helvetica.woff';

Some frameworks have a public directory, to which you could make absolute imports. However, this is not encouraged. To maintain consistency with EcmaScript and TypeScript, it is highly recommended that you create a path (alias) to this public folder instead, as shown in the following example:

✅ Suggested Usage

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./",
      "paths": [{
        "public/*": "./public/*",
        "@/*": "./src/*",
      }]
    }
  }

  import logo from 'public/img/logo.svg';
  import Helvetica from 'public/fonts/Helvetica.woff';
  // or
  import logo from '@/img/logo.svg';
  import Helvetica from '@/fonts/Helvetica.woff';

The example above is just a suggestion in case you want to keep the 'public' directory, nothing prevents you from using it inside 'src' or changing its name. Don't get attached to our alias names in the examples, they are not recommendations, just examples. Use the aliases with which you feel most comfortable

🛠️ Frameworks

Despite its configuration option in tsconfig.json, it's ironic that TypeScript doesn't have native support for aliases. Nevertheless, third-party tools are necessary to enable this feature. Below is a list of frameworks that support aliases and how to configure them.

✧ TypeScript (tsc)

Installation

npm i -D tsc-alias

Usage

  // package.json
  {
    "scripts": {
      "build": "tsc --project tsconfig.json && tsc-alias -p tsconfig.json",
    }
  }

✧ Vite / Vitest

Installation

npm i -D vite-tsconfig-paths

Usage

  // vite.config.js
  import { defineConfig } from 'vite';
  import tsconfigPaths from 'vite-tsconfig-paths';
  
  export default defineConfig({
    plugins: [tsconfigPaths()],
  });

  // vitest.config.js
  import { defineConfig } from 'vitest/config';
  import tsconfigPaths from 'vite-tsconfig-paths';

  export default defineConfig({
    plugins: [tsconfigPaths()],
  });

✧ Next.js

Next.js has in-built support for the "paths" and "baseUrl" options of tsconfig.json and jsconfig.json files.

✧ Gatsby

soon

✧ Webpack

soon

🔥 absolute-import - rule

Controls whether the import can be absolute if the source is in the same directory.

Options:

• enableAlias: boolean

  // .eslintrc
  module.exports = {
    rules: {
      'typescript-paths/absolute-import': 'warn'
      // short for: 'typescript-paths/absolute-import': ['warn', { enableAlias: false } ]
    },
  };

✧ enableAlias: true

Encourages the use of aliases for imports even from the same directory or subdirectories.

❌ Fail

  import functionA from './function-a';
  import functionB from './path-2/function-b';
  import functionC from './path-1/path-3/function-c';

✅ Pass

  import functionA from '@/path/CURRENT-DIR/function-a';
  import functionB from '@/path/CURRENT-DIR/path-2/function-b';
  import functionC from '@/path/CURRENT-DIR/path-1/path-3/function-c';

✧ enableAlias: false (default)

Discourages the use of aliases for imports from the same directory or subdirectories.

❌ Fail

  import functionA from '@/path/CURRENT-DIR/function-a';
  import functionB from '@/path/CURRENT-DIR/path-2/function-b';
  import functionC from '@/path/CURRENT-DIR/path-1/path-3/function-c';

✅ Pass

  import functionA from './function-a';
  import functionB from './path-2/function-b';
  import functionC from './path-1/path-3/function-c';

🔥 absolute-export - rule

Controls whether the export can be absolute if the source is in the same directory.

Options

• enableAlias: boolean

  // .eslintrc
  module.exports = {
    rules: {
      'typescript-paths/absolute-export': 'warn'
      // short for: 'typescript-paths/absolute-export': ['warn', { enableAlias: false } ]
    },
  };

✧ enableAlias: true

Encourages the use of aliases for exports even from the same directory or subdirectories.

❌ Fail

  export functionA from './function-a';
  export { functionB } from './path-2/function-b';
  export * from './path-1/path-3/function-c';

✅ Pass

  export functionA from '@/path/CURRENT-DIR/function-a';
  export { functionB } from '@/path/CURRENT-DIR/path-2/function-b';
  export * from '@/path/CURRENT-DIR/path-1/path-3/function-c';

✧ enableAlias: false (default)

Discourages the use of aliases for exports from the same directory or subdirectories.

❌ Fail

  export functionA from '@/path/CURRENT-DIR/function-a';
  export { functionB } from '@/path/CURRENT-DIR/path-2/function-b';
  export * from '@/path/CURRENT-DIR/path-1/path-3/function-c';

✅ Pass

  export functionA from './function-a';
  export { functionB } from './path-2/function-b';
  export * from './path-1/path-3/function-c';

🔥 absolute-parent-import - rule

Encourages the use of absolute imports from parent directories.

Options:

• preferPathOverBaseUrl: boolean

Usage:

  // .eslintrc
  module.exports = {
    rules: {
      'typescript-paths/absolute-parent-import': 'warn'
      // short for: 'typescript-paths/absolute-parent-import': ['warn', { preferPathOverBaseUrl: true } ]
    },
  };

✧ preferPathOverBaseUrl: true (default)

Encourages the use of paths (aliases) defined in the tsconfig.json file instead of importing modules using the baseUrl attribute.

❌ Fail

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src", // default is "./*"
      "paths": [{}]
    }
  }

  // relative parent imports
  import functionA from '../function-a';
  import functionB from '../../service/function-b';
  import functionC from '../../helper/util/path/function-c';

  // baseUrl imports
  import functionD from 'config/function-d';
  import functionE from 'service/function-e';
  import functionF from 'helper/util/path/function-f';

✅ Pass

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src", // default is "./"
      "paths": [{
        "@/*": "./*"
      }]
    }
  }

  import functionA from '@/config/function-a';
  import functionB from '@/service/function-b';
  import functionC from '@/helper/util/path/function-c';

✅ Pass

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src", // default is "./*"
      "paths": [{
        "util/*": "./helpers/utils/*",
        "@service/*": "./service/*",
        "@/*": "./*" // the most generic path should be the last
      }]
    }
  }

  import { functionA } from '@/config';
  import functionB from '@service/function-b';
  import functionC from 'util/path/function-c';

✧ preferPathOverBaseUrl: false

Encourages the use of paths (aliases) if defined in the tsconfig.json file, otherwise allows and suggests the use of absolute imports using the baseUrl attribute.

❌ Fail

  // relative parent imports
  import functionA from '../function-a';
  import functionB from '../../service/function-b';
  import functionC from '../../helper/util/path/function-c';

✅ Pass

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src", // default is "./*"
      "paths": [{}]
    }
  }

  // baseUrl imports
  import functionA from 'config/function-a';
  import functionB from 'service/function-b';
  import functionC from 'helper/util/path/function-c';

✅ Pass

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src", // default is "./*"
      "paths": [{
        "@/*": "./*"
      }]
    }
  }

  // baseUrl imports
  import functionA from 'function-a';
  import functionB from 'service/function-b';
  import functionC from 'helper/util/path/function-c';

  // paths imports
  import functionD from '@/function-d';
  import functionE from '@/service/function-e';
  import functionF from '@/helper/util/path/function-f';

🔥 absolute-parent-export - rule

Encourages the use of absolute exports from parent directories.

Options:

• preferPathOverBaseUrl: boolean

Usage:

  // .eslintrc
  module.exports = {
    rules: {
      'typescript-paths/absolute-parent-export': 'warn'
      // short for: 'typescript-paths/absolute-parent-export': ['warn', { preferPathOverBaseUrl: true } ]
    },
  };

✧ preferPathOverBaseUrl: true (default)

Encourages the use of paths (aliases) defined in the tsconfig.json file instead of exporting modules using the baseUrl attribute.

❌ Fail

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src", // default is "./*"
      "paths": [{}]
    }
  }

  // relative parent exports
  export functionA from '../function-a';
  export { functionB } from '../../service/function-b';
  export * from '../../helper/util/path/function-c';

  // baseUrl exports
  export functionD from 'config/function-d';
  export { functionE } from 'service/function-e';
  export * from 'helper/util/path/function-f';

✅ Pass

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src", // default is "./"
      "paths": [{
        "@/*": "./*"
      }]
    }
  }

  export functionA from '@/config/function-a';
  export { functionB } from '@/service/function-b';
  export * from '@/helper/util/path/function-c';

✅ Pass

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src", // default is "./*"
      "paths": [{
        "util/*": "./helpers/utils/*",
        "@service/*": "./service/*",
        "@/*": "./*" // the most generic path should be the last
      }]
    }
  }

  export functionA from '@/config';
  export { functionB } from '@service/function-b';
  export * from 'util/path/function-c';

✧ preferPathOverBaseUrl: false

Encourages the use of paths (aliases) if defined in the tsconfig.json file, otherwise allows and suggests the use of absolute imports using the baseUrl attribute.

❌ Fail

  // relative parent exports
  export functionA from '../function-a';
  export { functionB } from '../../service/function-b';
  export * from '../../helper/util/path/function-c';

✅ Pass

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src", // default is "./*"
      "paths": [{}]
    }
  }

  // baseUrl exports
  export functionA from 'config/function-a';
  export { functionB } from 'service/function-b';
  export * from 'helper/util/path/function-c';

✅ Pass

  // tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": "./src", // default is "./*"
      "paths": [{
        "@/*": "./*"
      }]
    }
  }

  // baseUrl exports
  export functionA from 'function-a';
  export { functionB } from 'service/function-b';
  export * from 'helper/util/path/function-c';

  // paths exports
  export functionD from '@/function-d';
  export { functionE } from '@/service/function-e';
  export * from '@/helper/util/path/function-f';