How to Fix the ‘Export Objects, Only Functions’ Babel Error

Encountering the “Plugin/preset files are not allowed to export objects, only functions” error can stop your development process in its tracks. This common issue, often seen with tools like Babel, happens when your configuration file exports a plain object instead of the required function. Understanding why this happens and how to fix it is key to a smooth build process. This guide will walk you through the simple steps to resolve this error and get your code compiling again.

What Causes the ‘Export Objects, Only Functions’ Error?

The root of this error lies in how tools like Babel process their configurations. Babel is designed to be highly extensible through plugins and presets, which are essentially sets of instructions for transforming your code.

To apply these transformations correctly, Babel needs to initialize each plugin or preset. It does this by calling it as a function. This functional approach allows Babel to pass in its API and other contextual information, enabling dynamic configurations and caching for better performance.

When you export a static object directly, Babel has nothing to execute. It sees the object but cannot call it, leading to the “not allowed to export objects, only functions” error. It’s a strict requirement that ensures the entire ecosystem works as intended.

How to Identify the Problem in Your Configuration

Pinpointing the source of the error is usually straightforward. The error message will typically point to the specific plugin or preset file causing the issue. Your first step should be to navigate to that file in your project.

Once you have the file open, look at the very end where you export your module. You are looking for a line that resembles module.exports = { ... };. If you see this, you have likely found the culprit.

The code is exporting an object literal directly. While this is valid JavaScript syntax in many contexts, it is incorrect for a Babel plugin or preset file. The fix involves wrapping this object inside a function.

The Correct Way to Export a Babel Plugin

A Babel plugin must be exported as a function that returns the plugin’s configuration object. This function typically receives the Babel API as its first argument, which you can use to access various helpers and information.

The core of a plugin is the `visitor` object. This object contains methods that correspond to different types of nodes in your code’s Abstract Syntax Tree (AST). Babel traverses the AST and executes your visitor methods when it encounters a matching node type.

Here is a basic template for a valid plugin export:


module.exports = function(babel) {
return {
visitor: {
Identifier(path) {
// Your transformation logic goes here
}
}
};
};

By wrapping the configuration in a function, you allow Babel to properly initialize it during the build process.

How to Properly Structure a Babel Preset

Similar to plugins, presets must also be exported as functions. A preset is essentially a pre-configured collection of plugins and can even include other presets. This makes it easy to add support for language features like React (JSX) or specific ECMAScript versions.

The function for a preset receives an API object that allows you to do things like cache the configuration. Caching is a powerful feature that can significantly speed up subsequent builds by avoiding redundant computations.

Incorrect Export (Object)Correct Export (Function)
module.exports = {
presets: ['@babel/preset-env']
};
module.exports = function(api) {
api.cache(true);
return {
presets: ['@babel/preset-env']
};
};

The functional structure gives you more control and ensures compatibility with Babel’s internal mechanisms.

Check for Mismatched Plugin and Preset Versions

Sometimes, your export syntax might be perfectly correct, but the error still persists. In such cases, the problem could be due to version conflicts between your Babel core package and the plugins or presets you are using.

An older plugin might not be compatible with a newer version of Babel, or vice-versa. This can lead to a variety of unexpected errors, including the one about exporting objects.

To resolve this, you should:

  • Check your `package.json` file for all packages prefixed with `@babel/`.
  • Ensure that all of these packages are on the same major version (e.g., 7.x.x).
  • Run `npm update` or `yarn upgrade` to bring all packages to their latest compatible versions.

Keeping your dependencies in sync is a crucial best practice that prevents many hard-to-diagnose issues.

When in Doubt, Consult the Documentation

The JavaScript ecosystem moves quickly, and package APIs can change. If you have tried the steps above and are still stuck, your next best move is to check the official documentation for the specific plugin or preset causing the error.

The documentation on NPM or the project’s GitHub page will almost always include a “Usage” section with clear examples of how to configure it correctly. This is the most reliable source of information and can save you hours of frustration. Look for the recommended export format and compare it against your own code to spot any differences.

Frequently Asked Questions

What does “Plugin/preset files are not allowed to export objects, only functions” mean?
This error means your Babel configuration file is exporting a static JavaScript object directly. Babel requires you to export a function that returns an object, so it can properly initialize the plugin or preset during its build process.

Is this error specific to Babel?
While this exact error message is strongly associated with Babel, the underlying principle is common in other configurable tools like Webpack or ESLint. Many modern development tools use functional configurations to allow for more dynamic and powerful setups.

How do I check my Babel plugin versions for compatibility?
Open your project’s `package.json` file and look for all dependencies that start with `@babel/`. Make sure they all share the same major version number, for example, `^7.15.0`. If you see a mix of major versions like 6 and 7, you have a compatibility issue that needs to be fixed.

Can a Babel plugin ever export an object directly?
No, according to the official Babel plugin handbook and API, a plugin file must always export a function. This is a strict requirement for Babel to correctly instantiate and use the plugin with the necessary context and APIs.

What is the difference between a Babel plugin and a preset?
A Babel plugin is a small piece of code that performs a single, specific code transformation, like converting arrow functions. A preset is a collection of related plugins grouped together for convenience, such as `@babel/preset-react`, which includes all the plugins needed to transpile JSX.