babel-plugin-filter-imports

4.0.0 verified Sat Apr 25 auth: no javascript

A Babel 7 plugin that removes references to specified imports in JavaScript modules, useful for stripping debugging code from production builds when combined with dead code elimination (e.g., UglifyJS). Version 4.0.0 supports Node >=8, with legacy branches for Babel 6 and 5. Key differentiators: configurable per-module import removal, optional retention of import declarations via keepImports option, and compatibility with default/namespace imports. Released under the ember-cli organization, actively maintained with SemVer.

Common errors

error Error: [BABEL] unknown: Cannot find module 'babel-plugin-filter-imports' ↓

cause Plugin not installed or not in node_modules.

fix

Run 'npm install --save-dev babel-plugin-filter-imports'

error Error: Plugin configuration must be an object with an 'imports' key (since v1.x) ↓

cause Using the old flat configuration format without imports wrapper.

fix

Change the plugin config to: ['filter-imports', { imports: { 'module': ['import'] } }]

error TypeError: Cannot read property 'filter' of undefined (when using namespace import) ↓

cause Namespace import '*' not properly configured in imports object.

fix

Ensure options.imports['module'] includes '*' to remove namespace imports.

error Input source code still contains removed imports (keepImports default behavior) ↓

cause Default keepImports is true, so import declarations remain even if references are removed.

fix

Set keepImports: false to remove import declarations as well.

Warnings

breaking Configuration object changed in v1.x: imports must be nested under 'imports' key. ↓

fix Wrap your import specifiers into { imports: { ... } } as shown in the README.

breaking v2.x removed support for Babel 6. Only Babel 7 is supported. ↓

fix Upgrade to Babel 7, or use the babel6 branch for legacy support.

gotcha Plugin only removes references, not import declarations by default. Use keepImports: false to also remove import statements. ↓

fix Set keepImports: false in options if you want the import statements removed.

gotcha The plugin does not handle CommonJS require() calls; only ESM import/export syntax is transformed. ↓

fix Use ESM imports or pre-process with Babel to convert require to imports.

Install

npm install babel-plugin-filter-imports

yarn add babel-plugin-filter-imports

pnpm add babel-plugin-filter-imports

Imports

String (import name)
wrong
```
const warn = require('debugging-tools').warn;
```
correct
```
import { warn } from 'debugging-tools';
```
This plugin operates on ESM import statements; it does not affect CommonJS require() calls.
default import
wrong
```
import { default } from 'debugging-tools';
```
correct
```
import log from 'debugging-tools';
```
Use 'default' in the plugin config to remove the default import.
namespace import
wrong
```
import { * } from 'debugging-tools';
```
correct
```
import * as utils from 'debugging-tools';
```
Use '*' in the plugin config to remove a namespace import (star import).
plugin configuration
wrong
```
["filter-imports", { "debugging-tools": ["warn"] }]
```
correct
```
["filter-imports", { imports: { "debugging-tools": ["warn"] } }]
```
Breaking change in v1.x: options must be nested under imports key. Old direct format no longer works.

Quickstart

Demonstrates configuration with multiple imports, keepImports option, and resulting code transformation.

// Install plugin
// npm install --save-dev babel-plugin-filter-imports

// .babelrc or babel.config.js
{
  "plugins": [
    ["filter-imports", {
      "imports": {
        "debugging-tools": ["warn", "log"],
        "another-module": ["default"]
      },
      "keepImports": false
    }]
  ]
}

// Input source code
import { warn, log } from 'debugging-tools';
import defaultFunc from 'another-module';

function example() {
  warn('warning');
  log('info');
  defaultFunc();
}

// Transformed output (keepImports: false)
function example() {
  ;
  ;
  ;
}

// With keepImports: true, import statements remain but references are removed
function example() {
  ;
  ;
  ;
}