babel-plugin-bare-import-rewrite

2.0.0 verified Sat Apr 25 auth: no javascript

A Babel plugin that rewrites bare import specifiers (like 'lodash') to browser-compatible URL-based paths for use without a bundler, currently at stable version 2.0.0. It resolves bare imports to absolute or relative URLs pointing to node_modules on a web server, with configurable options like modulesDir, alwaysRootImport, and ignorePrefixes. This plugin is a pragmatic solution until native import maps gain full browser support, making it distinct from bundler-based approaches like Webpack or Rollup. It supports ESM, CJS, and TypeScript projects using Babel, actively maintained, and requires @babel/core >=7.8.3.

Common errors

error Error: Cannot find module '@babel/core' ↓

cause @babel/core is a peer dependency not installed.

fix

Run 'npm install @babel/core' to install the peer dependency.

error TypeError: plugin is not a function ↓

cause Importing the default export incorrectly in ESM.

fix

Use 'import bareImportRewrite from 'babel-plugin-bare-import-rewrite'' (default) or 'import { default as bareImportRewrite } from '...'

error The 'resolve' method throws 'Cannot read property 'split' of undefined' ↓

cause Calling require('babel-plugin-bare-import-rewrite') and then treating it as the resolve function.

fix

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

error Uncaught Error: Cannot find module 'lodash' while resolving bare import ↓

cause Module not found in node_modules or 'failOnUnresolved' is set to false causing silent failure.

fix

Install the missing module with 'npm install lodash' or check the module name.

Warnings

breaking In version 2.0.0, the default value of 'preserveSymlinks' changed from false to true. ↓

fix If you rely on symlink resolution, set preserveSymlinks: false in plugin options.

deprecated The option 'processAtProgramExit' is deprecated and may be removed in a future major version. ↓

fix Remove the option from your config.

gotcha If 'modulesDir' is not set, the plugin may generate relative paths that break in different deployment contexts. ↓

fix Always set modulesDir to an absolute URL path like '/node_modules' or use the default.

gotcha Resolving modules from multiple directories using 'resolveDirectories' requires careful ordering; leftmost takes precedence. ↓

fix Ensure the most important node_modules directory is first in the array.

breaking Node.js 10 or above is required; older versions are unsupported. ↓

fix Upgrade Node.js to version 10.13.0 or later.

gotcha The 'resolve' export is synchronous and should not be used for async workflows. ↓

fix Use the plugin only in synchronous Babel transformations; wrap async calls if needed.

Install

npm install babel-plugin-bare-import-rewrite

yarn add babel-plugin-bare-import-rewrite

pnpm add babel-plugin-bare-import-rewrite

Imports

resolve

wrong

const resolve = require('babel-plugin-bare-import-rewrite').resolve

correct

import { resolve } from 'babel-plugin-bare-import-rewrite'

The package has a named export 'resolve' for programmatic use. In CJS, you can destructure from require.

default

wrong

const bareImportRewrite = require('babel-plugin-bare-import-rewrite')

correct

import bareImportRewrite from 'babel-plugin-bare-import-rewrite'

The plugin is the default export. For CJS, require returns the plugin function directly (no .default).

resolve

wrong

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

correct

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

Common mistake: importing the whole module instead of destructuring resolve.

Quickstart

Shows minimal Babel config and the transformation of a bare import to a URL path for browser use.

// .babelrc
{
  "plugins": [
    ["bare-import-rewrite", {
      "modulesDir": "/node_modules",
      "alwaysRootImport": ["lodash"],
      "failOnUnresolved": true
    }]
  ]
}

// Input: import _ from 'lodash';
// Output: import _ from '/node_modules/lodash/index.js';