JSPM

📖 Description

ESLint Rules that enables the automatic fixing of relative paths to absolute paths based on the paths or baseUrl from tsconfig.json

🗂️ Summary

• Installation
• Requirements
• Usage
• Frameworks
  • TypeScript (tsc)
  • Vite / Vitest
  • Next.js
  • Gatsby - soon
  • Webpack - soon
• Rules
  • absolute-import
  • absolute-export
  • absolute-parent-import
  • absolute-parent-export

🎒 Motivation

npm i -D eslint-plugin-typescript-paths

🧩 Requirements

It is recommended that you have already set up eslint-plugin-import, @typescript-eslint and eslint-import-resolver-typescript in your project.

Alternatively, you can simply use a level 2 configuration from Kiskadee ESLint Setup that already includes all the prerequisite configuration and additionally supports this plugin.

🪁 Usage

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
    },
  };

If you want to customize the rules, define typescript-paths plugin.

  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.

❌ Avoid using this

  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.build.json && tsc-alias -p tsconfig.build.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()],
    test: {
      include: ['**/*.test.ts'],
      globals: true,
    },
  });

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';