Babel Plugin Explicit Exports References

1.0.2 verified Sat Apr 25 auth: no javascript

A Babel plugin that transforms internal references to a module's exports so they use `module.exports` instead of direct local variable references. This enables mocking of exported functions in Jest with Babel/TypeScript, even when those functions call each other internally within the same module. Version 1.0.2, actively maintained. Key differentiator: addresses the common problem of internal function references not being mockable in test environments, unlike other solutions that require manual refactoring or alternative mocking strategies.

Common errors

error Cannot find module 'babel-plugin-explicit-exports-references' ↓

cause The plugin is not installed as a dev dependency or is not in node_modules.

fix

Run 'npm install --save-dev babel-plugin-explicit-exports-references' to install the plugin.

error ReferenceError: module is not defined ↓

cause The plugin transforms code to use `module.exports`, but the environment does not have a CommonJS 'module' object (e.g., running in a browser without bundling).

fix

Ensure the transformed code is processed by a bundler like Webpack that provides CommonJS compatibility, or only use in test environments with Jest.

error Jest spyOn does not mock internal calls ↓

cause The Babel plugin is not enabled or configured correctly, so internal references remain as direct function calls.

fix

Ensure 'explicit-exports-references' is in your babel.config.js under the 'test' environment and that Jest is using Babel for transformation.

Warnings

gotcha Using this plugin in production or non-test environments can increase build size and introduce performance overhead. ↓

fix Only enable the plugin when NODE_ENV is 'test' using Babel's env configuration.

breaking TypeScript enums are explicitly ignored and will not be transformed to use module.exports. ↓

fix Do not rely on this plugin for mocking enum references; consider using modules or classes instead.

deprecated The 'transformAssignExpr' option is considered unstable and may cause unexpected behavior. ↓

fix Avoid using { transformAssignExpr: true } unless absolutely necessary, and test thoroughly.

gotcha Assignment expressions are not transformed by default; only identifier references are. ↓

fix If you need assignment expressions transformed, enable the experimental 'transformAssignExpr' option.

gotcha The plugin only transforms identifier references within the same module; references from other modules are unaffected. ↓

fix No fix needed; this is intended behavior as cross-module mocking is handled by Jest's module system.

Install

npm install babel-plugin-explicit-exports-references

yarn add babel-plugin-explicit-exports-references

pnpm add babel-plugin-explicit-exports-references

Imports

default

wrong

import plugin from 'babel-plugin-explicit-exports-references'

correct

module.exports = { plugins: ['explicit-exports-references'] }

This is a Babel plugin, not a regular import. It is configured in babel.config.js as a string reference.

plugin options

wrong

plugins: [['explicit-exports-references', { transformAssignExpr: 'true' }]]

correct

plugins: [['explicit-exports-references', { transformAssignExpr: true }]]

Options are passed as an array with the plugin name, not as an object directly.

env-specific configuration

wrong

module.exports = { plugins: ['explicit-exports-references'], only: ['test'] }

correct

module.exports = { env: { test: { plugins: ['explicit-exports-references'] } } }

Use Babel's env property to conditionally enable the plugin only in test environments.

Quickstart

Installs and configures the plugin to enable mocking of internal function references in Jest tests.

// install: npm install --save-dev babel-plugin-explicit-exports-references
// babel.config.js
module.exports = {
  presets: ['@babel/preset-env'],
  env: {
    test: {
      plugins: ['explicit-exports-references']
    }
  }
};

// Example: myModule.ts
export function foo() {
  throw new Error('expensive');
}
export function bar() {
  foo();
  return 5;
}

// After transformation (only in test), bar internally calls module.exports.foo() instead of foo()
// So mocking module.exports.foo in Jest works:
// myModule.test.ts
import * as myModule from './myModule';
jest.spyOn(myModule, 'foo').mockImplementation(() => {});
const result = myModule.bar();
expect(myModule.foo).toHaveBeenCalled();
expect(result).toBe(5);