This site runs best with JavaScript enabled.

Misunderstanding ES6 Modules, Upgrading Babel, Tears, and a Solution

Those are supposed to be_tears...

On October 29th, 2015, Sebastian McKenzie, James Kyle, and the rest of the Babel team dropped a huge major release for frontend developers...

On October 29th, 2015, Sebastian McKenzie, James Kyle, and the rest of the Babel team dropped a huge major release for frontend developers everywhere: Babel 6.0.0. It's totally awesome. No longer just a transpiler, it's now a super pluggable JavaScript tooling platform. As a community, we've only scratched the surface of what it is capable of and I'm excited (and cautiously optimistic) for what the future holds in JavaScript tooling.

All of that said, Babel 6.0.0 was an enormous breaking change. It had a bit of a rocky start. It's not entirely straightforward to upgrade and takes some learning. This post isn't going to talk about how you upgrade Babel, necessarily. I'm just going to touch on what I learned about my own code when Babel fixed a bug I relied on heavily... Here are some resources I recommend you check out before you try to upgrade your stuff from Babel 5 to Babel 6:

Clearing up the Babel 6 Ecosystem

Quick guide: how to update Babel 5.x -> 6.x

ES6 Modules

Upgrading for me would not have been that difficult if I had understood the ES6 Modules specification correctly. Babel 5 allowed misuse of export and import statements and Babel 6 fixed this problem. At first I thought this may be a bug. I asked about it on Stack Overflow and Logan Smyth informed me that I fundamentally misunderstood ES6 modules and that Babel 5 had facilitated that misunderstanding (writing a transpiler is hard).

Near-midlife crisis

At first, I didn't quite understand what Logan meant, but when I had the time to dedicate to upgrading my app, this happened

Tyler McGinnis, Josh Manders, and I went back and forth quite a bit on this thread. It's probably hard to follow, but this is when I realized that the problem wasn't exporting the object as a default, but how I expected that I could import the object.

I always assumed that I could export an object as the default and then destructure the pieces out of that object I needed, like so:

1// foo.js
2const foo = {baz: 42, bar: false}
3export default foo
5// bar.js
6import {baz} from './foo'

Babel 5 allowed this because of how it transpiled the export default statement. However this is technically incorrect according to the spec which is why Babel 6 (correctly) removed that capability and effectively broke over 200 of my modules in my application at work.

I finally figured out how things really work when I reviewed Nicolás Bevacqua's blogpost

And I discovered why what I had been doing wouldn't work when I read Axel Rauschmayer's blogpost

Here's the basic idea: ES6 modules are supposed to be statically analyzable (runtime cannot change the exports/imports) so it can't be dynamic. In the example above, I could change the foo object's properties at runtime and then my import statement could import that dynamic property, like this:

1// foo.js
2const foo = {}
3export default foo
4somethingAsync().then(result => (foo[result.key] = result.value))
6// bar.js
7import {foobar} from './foo'

We'll assume that result.key is 'foobar'. In CommonJS this would work just fine because the require statements happen at runtime (when they're required):

1// foo.js
2const foo = {}
3module.exports = foo
4somethingAsync().then(result => result => (foo[result.key] = result.value))
6// bar.js
7const {foobar} = require('./foo')

However, because the ES6 specification states that imports and exports must be statically analyzable, you can't accomplish this dynamic behavior in ES6.

So that's the why for Babel's change. It's no longer possible to do this and that's a good thing.

What does this mean?

Coming up with a good way to describe this in prose has proven difficult, so I hope a bunch of code examples and comparisons will be instructive

The problem I had was I was combining ES6 exports with CommonJS require. I would do something like this:

1// add.js
2export default (x, y) => x + y
4// bar.js
5const three = require('./add')(1, 2)

With the changes that Babel made, I had three choices:

Option 1: require with default

1// add.js
2export default (x, y) => x + y
4// bar.js
5const three = require('./add').default(1, 2)

Option 2: ES6 modules 100%

1// add.js
2export default (x, y) => x + y
4// bar.js
5import add from './add'
6const three = add(1, 2)

Option 3: CommonJS 100%

1// add.js
2module.exports = (x, y) => x + y
4// bar.js
5const three = require('./add')(1, 2)

How did I fix it?

After a few hours I got the build running and the tests passing. I had two different approaches for different scenarios:

  1. I changed the export to be CommonJS (module.exports) rather than ES6 (export default) so I could continue to require it as I have been doing.
  2. I did a fancy regex find and replace (should have used a codemod) to change the other require statements from require('./thing') to require('./thing').default

This worked out pretty well. The biggest challenge was just understanding how the ES6 modules spec works and how Babel transpiles it down to CommonJS so it can interoperate. Once I figured that out it was just monkey work to update my code to follow this convention.


Try to avoid mixing ES6 modules and CommonJS. I personally would say just go with ES6 modules for everything. One of the reasons that I mixed them in the first place was so I could do a one-liner require and immediately use the required module (like require('./add')(1, 2)). But that's really not a big enough benefit IMO.

If you feel like you must combine them, you might consider using one of the following babel plugins/presets:




The real lesson from all of this is that we should learn how things are supposed to work. I could have saved myself a great deal of time if I had just understood how the ES6 module spec actually is intended to work.

You may benefit from this lesson I made demonstrating how to upgrade from Babel 5 to Babel 6:

Also, remember that nobody’s perfect and we’re all learning here :-) See you on Twitter!


More examples:

Before the change with Babel, a require statement was similar to:

1import add from './add'
2const three = add(1, 2)

But after the change in Babel, the require statement now becomes more like:

1import * as add from './add'
2const three = add.default(1, 2)

What caused the problem for me was that now the add variable is no longer the default export, but an object that has all the named exports and the default export (under the default key).

Named Exports:

It’s notable that you can also use named exports and I recommend this with utility modules. This will allow you to do the destructuring-like syntax in the import statement (warning, despite what it looks like it’s not actually destructing due to the static analysis reasons mentioned earlier). So you could do:

1// math.js
2const add = (x, y) => x + y
3const subtract = (x, y) => x - y
4const multiply = (x, y) => x \* y
5export {add, subtract, multiply}
7// foo.js
8import {subtract, multiply} from './math'

This gets really awesome/exciting with tree shaking.

Personally, I generally recommend that for a component (like a React component or an Angular service) you’ll want to use default exports (you’re importing a specific thing, single file, single component, you know 😀). But for utility modules you generally have various pure functions that can be used independently. This is a great use case for named exports.

Discuss on TwitterEdit post on GitHub

Share article
Kent C. Dodds

Kent C. Dodds is a JavaScript software engineer and teacher. He's taught hundreds of thousands of people how to make the world a better place with quality software development tools and practices. He lives with his wife and four kids in Utah.

Join the Newsletter

Kent C. Dodds