babel-plugin-fully-specified

1.3.1 verified Sat Apr 25 auth: no javascript

A Babel plugin (v1.3.1) that automatically adds mandatory file extensions to import paths, transforming bare specifiers like './path' into fully-specified paths like './path/index.js'. It targets authors of ESM packages with 'type': 'module' in package.json, ensuring compliance with Node.js ESM mandatory file extension rules. The plugin resolves directory imports to index files with the correct extension, supports TypeScript/TSX, and offers options for custom extension lists and package inclusion. Alternative tools include manual rewriting or other Babel plugins, but this plugin's focus on batch transformation for build pipelines sets it apart. Released in Jan 2026, it has active maintenance and supports dynamic import detection but not transformation.

Common errors

error Module not found: Error: Can't resolve './path' in '/path/to/file' ↓

cause Bare import without extension in ESM context; Node.js requires fully-specified paths for ESM.

fix

Configure the Babel plugin to add extensions during build, or manually add the correct extension (e.g., './path/index.js').

error Error: Cannot find module 'babel-plugin-fully-specified' ↓

cause Plugin not installed or not in the same node_modules resolution chain as babel.

fix

Run 'npm install --save-dev babel-plugin-fully-specified' from the project root where babel.config.js resides.

error TypeError: (0 , _fullySpecified.default) is not a function ↓

cause Attempting to import the plugin as a default ES import instead of using CommonJS require.

fix

Use require('babel-plugin-fully-specified') or reference it as a string in plugins array.

Warnings

breaking Dynamic imports are not transformed; they will remain bare-specified. ↓

fix Manually add file extensions to dynamic import() calls, or use a different plugin that handles dynamic imports.

gotcha Plugin may incorrectly prioritize file over directory when both exist (e.g., './path' and './path.js'), potentially resolving to the file without index extension. ↓

fix Update to v1.1.2+ which fixes this behavior to prioritize files before directories.

breaking For packages listed in includePackages, the plugin adds extensions to all imports from those packages, which may break Node.js resolution for packages that are not fully-specified already. ↓

fix Only include packages that are known to be ESM and require fully-specified imports; test thoroughly after enabling.

deprecated The option 'esExtensionDefault' may be renamed in future versions; check changelog for updates. ↓

fix Monitor the repository for breaking changes; currently remains in use as of v1.3.1.

Install

npm install babel-plugin-fully-specified

yarn add babel-plugin-fully-specified

pnpm add babel-plugin-fully-specified

Imports

default
wrong
```
import fullySpecified from 'babel-plugin-fully-specified'
```
correct
```
module.exports = require('babel-plugin-fully-specified')
```
This is a CommonJS plugin; in Node.js, use require(). In browser-based transforms, typically used via babel.config.js where require() is standard.
babel-plugin-fully-specified
wrong
```
plugins: [require('babel-plugin-fully-specified')]
```
correct
```
plugins: ['babel-plugin-fully-specified']
```
In Babel configuration, string references auto-resolve. Explicitly requiring it is unnecessary and may cause issues with Babel's plugin resolution if the plugin is not installed at the config's location.

BabelPluginFullySpecified

wrong

import { BabelPluginFullySpecified } from 'babel-plugin-fully-specified'; plugins: [BabelPluginFullySpecified]

correct

Internal server error