babel-plugin-webpack-aliases

1.1.3 verified Sat Apr 25 auth: no javascript deprecated

Babel 6 plugin that resolves webpack resolve.alias during Babel transpilation, useful for testing environments where webpack is not available. Version 1.1.3 (stable, last release 2016). It replaces require/import paths with relative paths based on webpack config aliases. Maintained as a fork of babel-plugin-webpack-alias. No updates since 2016; consider alternatives like module-resolver for newer Babel versions.

Common errors

error Module not found: Can't resolve '...' in '...' ↓

cause Alias path not correctly resolved because webpack config path is wrong or alias mapping is incorrect.

fix

Check the config option points to the correct webpack config file and that aliases are configured with absolute paths.

error TypeError: Cannot read property 'alias' of undefined ↓

cause Webpack config does not have a resolve.alias property or config export is invalid.

fix

Ensure webpack config exports an object with resolve.alias defined.

error Error: Options must be a string, an array, or an object ↓

cause Usage of babel-plugin-webpack-aliases outside of Babel config, e.g., as a module import.

fix

Do not import the plugin directly; use it only within Babel configuration.

Warnings

deprecated Plugin is no longer maintained and only supports Babel 6. Not compatible with Babel 7+. ↓

fix Migrate to babel-plugin-module-resolver for Babel 7+ compat.

gotcha Plugin expects webpack config to export an object. If using webpack-merge or other patterns, alias resolution may fail. ↓

fix Ensure webpack config is a plain object. Use require() to load config and verify resolve.alias exists.

gotcha Alias resolution is relative to the webpack config file location, not the project root. ↓

fix Use absolute paths in webpack aliases with path.resolve(__dirname, ...) to avoid confusion.

gotcha Does not support webpack resolve.alias fields with arrays or nested objects; only simple key-value string mappings. ↓

fix Flatten complex alias configurations into simple string mappings.

gotcha If findConfig option is true, plugin uses find-up but does not handle multiple matching configs well. ↓

fix Explicitly set config path to avoid ambiguity.

Install

npm install babel-plugin-webpack-aliases

yarn add babel-plugin-webpack-aliases

pnpm add babel-plugin-webpack-aliases

Imports

plugin

wrong

import babelPluginWebpackAliases from 'babel-plugin-webpack-aliases'

correct

Add to .babelrc plugins array: ['babel-plugin-webpack-aliases', { config: './webpack.config.js' }]

This is a Babel plugin, not a JavaScript module. It is used via .babelrc or babel.config.js, not imported directly.

plugin

wrong

require('babel-plugin-webpack-aliases') in code

correct

In babel.config.js: plugins: [['babel-plugin-webpack-aliases', { config: './webpack.config.js' }]]

The plugin is configured in Babel config, not required in application code.

plugin

wrong

Incorrect inline plugin syntax without array

correct

In package.json babel section: "plugins": [["babel-plugin-webpack-aliases", { "config": "webpack.config.js" }]]

When using string shorthand, arguments are passed as an array: [pluginName, options].

Quickstart

Configure plugin in .babelrc with webpack config path; aliases are resolved to relative paths.

// .babelrc
{
  "plugins": [
    ["babel-plugin-webpack-aliases", {
      "config": "./webpack.config.js"
    }]
  ]
}

// webpack.config.js
module.exports = {
  resolve: {
    alias: {
      '@components': './src/components',
      '@utils': './src/utils'
    }
  }
};

// After Babel transpilation:
// import MyComponent from '@components/MyComponent';
// becomes:
// import MyComponent from './src/components/MyComponent';