babel-plugin-bare-import-rewrite

babel-plugin-bare-import-rewrite

Babel plugin to rewrite bare imports. In theory this will become obsolete if/when browsers get support for import maps. See domenic/package-name-maps for information about the proposal.

Install babel-plugin-bare-import-rewrite

This module requires node.js 10 or above and @babel/core.

npm i babel-plugin-bare-import-rewrite

Usage

Add bare-import-rewrite to plugins in your babel settings.

Settings

{
	"plugins": [
		["bare-import-rewrite", {
			"modulesDir": "/node_modules",
			"rootBaseDir": ".",
			"alwaysRootImport": [],
			"ignorePrefixes": ["//"],
			"failOnUnresolved": false,
			"resolveDirectories": ["node_modules"],
			"processAtProgramExit": false,
			"preserveSymlinks": true
		}]
	]
}

If the plugin settings object is omitted the defaults are used:

{
	"plugins": ["bare-import-rewrite"]
}

modulesDir

The URL path in which files from the node_modules directory will be published on the web server. This must be an absolute URL if provided (with or without hostname). Default undefined.

rootBaseDir

The project base directory. This should contain the package.json and node_modules of the application. Default process.cwd().

alwaysRootImport

This contains a list of module bare names which should always be forced to import from the root node_modules. ['**'] can be used to specify that all modules should be resolved from the root folder. No attempt is made to verify that overridden modules are compatible. Each element is used as a pattern to be processed with minimatch. Default [].

neverRootImport

This contains a list of module bare names which should never be forced to imported from the root node_modules. Processed with minimatch. Default [].

This example will force all modules to be loaded from the root node_modules except for some-exception:

{
	"alwaysRootImport": ["**"],
	"neverRootImport": ["some-exception"]
}

failOnUnresolved

By default an error is logged when an import could not be resolved, but it does not fail babel compilation. Setting this option to true will fail babel compilation with details.

resolveDirectories

Array of directories which should be search for resolving modules. If multiple directories are specified they are evaluated in order of importance. If the same module exists in both folders, the leftmost module directory is always taken. Defaults to ['node_modules'].

fsPath

Setting this option true forces use of platform specific path separators. This changes the default value of modulesDir to the absolute filesystem path of node_modules. This should generally be used when using absolute filesystem paths for bundling.

ignorePrefixes

This option can be set to an array of strings. Each represents a module name prefix to be ignored.

extensions

A list of extensions to use in resolver. Default ['.mjs', '.js', '.json'].

processAtProgramExit

This causes processing to occur during the babel Program.exit visitor. In general this option is not needed.

preserveSymlinks

This is passed to the resolve module. Default true.

.resolve(importModule, sourceFileName, pluginOptions) - Resolve absolute path.

This function is used internally by the babel plugin, is exposed so it can be used by analyzers to build a list of scripts being imported. The pluginOptions argument takes the same values as the babel plugin and uses the same defaults.

const {resolve} = require('babel-plugin-bare-import-rewrite');

const importModule = '@polymer/lit-element';
const pluginOptions = {
	"alwaysRootImport": ["@polymer/*"],
};
try {
	const absPath = resolve(importModule, __filename, pluginOptions);
	console.log(`The requested module ${importModule} is in ${absPath}.`);
} catch (e) {
	console.error(`Cound not resolve ${importModule}:`, e);
}

Web Server Support

Some web server software has support for live translation of JavaScript sources. These are meant for using during development and testing, a build step should be used to produce static translated sources for production deployments.

• fastify-babel can be used with fastify and fastify-static
• express-transform-bare-module-specifiers can be used with express

Feel free to open an issue or PR if you know of other node.js servers which can use this babel plugin to perform bare import rewrites.

Running tests

Tests are provided by xo and ava.

npm install
npm test

Attribution

This module is based on code found in polymer-build and polymer-analyzer.

babel-plugin-bare-import-rewrite for enterprise

Available as part of the Tidelift Subscription.

The maintainers of babel-plugin-bare-import-rewrite and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

Changelog

2.0.0 (2020-01-26)

⚠ BREAKING CHANGES

• bump requirement to node.js 10.13.0
• The modulesDir no longer defaults to /node_modules.

Features

• Add preserveSymlinks option (eb4b2b4), closes #23
• bump requirement to node.js 10.13.0 (8dbab86)
• Create processAtProgramExit option (#30) (ad99be5), closes #26
• Use relative path to node_modules by default (#22) (f9eaf0e)

Bug Fixes

• modulesDir default should be absolute FS path when fsPath is enabled (6f299bc)