eslint-plugin-esm-import

An ESLint plugin which enforces explicit .js extensions in local imports.

The purpose of this plugin is to

• help with the initial migration of a common.js project to ESM, by leveraging the eslint --fix feature:
  • import x from './x-file' -> import x from './x-file.js'
  • import y from './y-folder' -> import y from './y-folder/index.js'
• enforce explicit .js extensions on all relevant imports during development

NOTE This plugin will be usefult to you only if you've been writing ESM-style imports in an otherwise common.js project, using babel and/or tsc to transpile it, so you are now stuck with a large number of file imports which don't have extensions and folder imports which don't have index files and thus do not conform to the ESM spec.
This was a fairly standard practice ever since ES6 (ES2015) came out.

Key features

• leverages existing import resolvers from the ESLint configuration (e.g. node, webpack, typescript)
• honors the convention of importing .ts and .tsx files as .js
• configurable list of ignored extensions (see Configure)
• configurable list of index files (see Configure)

Inspired by eslint-plugin-require-extensions, which only recognizes imports which start with ./, meaning it doesn't know how to handle imports which use resolver aliases (resolve.alias from Webpack conf or compilerOptions.paths from tsconfig and so on), which are usually the vast majority of imports in complex projects.

Install

ESLint	This package	eslint config example
v9	v1.0.1	eslint.config.js
v8	v0.0.1	.eslintrc
< v8	unsupported, but try v0.0.1

1. Install

1npm install --save-dev eslint-plugin-esm-import

2. Add these snippets to your eslint.config.js (see the table above for earlier ESLint versions)

1import esmImport from 'eslint-plugin-esm-import';
2export default [
3  {
4    plugins: {
5      'esm-import': esmImport
6    },
7    rules: {
8      ...esmImport.configs.recommended.rules
9    }
10  }
11]

Restart ESLint server to force conf reload in your IDE (in VSCode: Help > Show all commands > Restart ESLint server).

3. Code

1// source.js
2import RelativeFile from '../../shared/components/RelativeFile';
3import AliasedFile from 'Components/AliasedFile';   // provided there's a Components alias
4import AliasedFolder from 'Modules/aliased-folder'; // provided there's a Modules alias

4. Lint

1> ./node_modules/.bin/eslint ./src/source.js
2
3source.js
4  1:1  error  Local imports and exports must end with .js   esm-import/extensions
5  1:1  error  Local imports and exports must end with .js   esm-import/extensions
6  1:1  error  Importing a directory requires /index.js      esm-import/extensions
7
8✖ 3 problems (3 errors, 0 warnings)
9  3 errors and 0 warnings potentially fixable with the `--fix` option.

The purpose of the GH action is to run eslint in order to show the plugin in action:

5. Fix

1> ./node_modules/.bin/eslint --fix ./src/source.js

1// source.js
2import RelativeFile from '../../components/RelativeFile.js';
3import AliasedFile from 'components/AliasedFile.js';
4import AliasedFolder from 'Modules/aliased-folder/index.js';

Configure

The plugin allows you to configure:

• the list of ignored extensions, so this plugin can ignore imports which end with any of those extensions (defaults to [".js", ".cjs", ".json", ".css", ".scss"])
• the list of index files, in order to recognize that a folder got resolved to an index file and thus knows that the fix is to append /index.js, not .js (defaults to ["index.js", "index.jsx", "index.ts", "index.tsx"])

1// eslint.config.js example settings
2settings: {
3  'esm-import': {
4    ignore: ['.js', '.cjs', '.json', '.css', '.scss', '.svg', '.png', '.gif', '.mp3'],
5    index: ['index.js', 'index.jsx', 'index.ts', 'index.tsx']
6  }
7}

TypeScript

Make sure you define extension aliases in your Webpack configuration, otherwise eslint won't be able to resolve imports of TS files from JS as .js:

1  resolve: {
2    extensionAlias: {
3      '.js': [
4        '.ts',
5        '.tsx',
6        '.d.ts',
7      ],
8    },
9  },

Background info

eslint-plugin-import has no plans to treat ts imports as js.
TypeScript has no plans to transform nor enforce extensions.

Changelog

CHANGELOG.md

Cutting a new version

After changes are made:

1. Test whether the plugin still does its job by running npm run lint and npm run fix.
2. Bump the project's version in the package.json
3. Populate the CHANGELOG.md
4. Run npm publish --auth-type legacy
5. When asked to log in use sematext npm account (you'll need 2FA OTP).