Custom Import Path Transformer

Build a Babel plugin that transforms import paths in JavaScript modules based on configurable pattern mappings.

Problem

Create a Babel plugin that rewrites import declarations to match path aliases. The plugin should:

• Transform import paths based on user-defined pattern mappings
• Preserve the original import structure (named, default, namespace, side-effect imports)
• Handle invalid or missing configurations gracefully without errors

Requirements

Path Transformation

The plugin accepts a configuration object with path mappings:

{
  "pathMappings": {
    "@utils/*": "./src/utilities/*",
    "@components/*": "./src/components/*"
  }
}

When the plugin encounters an import matching a pattern (e.g., @utils/logger), it transforms it to the mapped path (e.g., ./src/utilities/logger). The * wildcard matches any path segment.

Import Structure Preservation

The plugin must preserve all aspects of the import:

• Named imports should remain as named imports
• Default imports should remain as default imports
• Namespace imports (import * as name) should remain as namespace imports
• Side-effect imports (import './file') should be transformed but maintain their side-effect nature

Configuration Validation

The plugin should validate that the configuration object is properly structured. If the configuration is missing or invalid, the plugin should skip transformation gracefully without throwing errors.

Test Cases

• Given an import statement import { log } from '@utils/logger' and a mapping "@utils/*": "./src/utilities/*", the plugin transforms it to import { log } from './src/utilities/logger' @test

• Given an import statement import Button from '@components/Button' and a mapping "@components/*": "./src/components/*", the plugin transforms it to import Button from './src/components/Button' @test

• Given an import statement import * as utils from '@utils/helpers' and a mapping "@utils/*": "./src/utilities/*", the plugin transforms it to import * as utils from './src/utilities/helpers' @test

• Given an import statement import '@utils/polyfill' and a mapping "@utils/*": "./src/utilities/*", the plugin transforms it to import './src/utilities/polyfill' @test

• Given multiple import statements with different patterns, the plugin transforms only those matching configured mappings and leaves others unchanged @test

• Given a plugin configuration without pathMappings or with an empty object, the plugin processes the code without transformations and without errors @test

Implementation

@generates

API

/**
 * Babel plugin that transforms import paths based on configured mappings.
 *
 * @returns {Object} Babel plugin object with visitor methods
 */
export default function importPathTransformer() {
  return {
    name: "import-path-transformer",
    visitor: {
      // Plugin implementation
    }
  };
}

Dependencies { .dependencies }

@babel/core { .dependency }

Provides the core Babel transformation API and plugin system infrastructure.

@babel/helper-plugin-utils { .dependency }

Provides utilities for declaring Babel plugins with proper configuration handling.

@babel/types { .dependency }

Provides builders and validators for AST node manipulation.