This site runs best with JavaScript enabled.

Pure Modules

How you write your ES Modules impacts the performance and maintainability of your code.

A few weeks ago, I saw this tweet from Ingvar Stepanyan:

Followed by this one:

These tweets resonated with me because it really would make a huge difference for JavaScript engines and the performance of ES Modules. It really was a missed opportunity. There's not much we can do about it at this point (though you could simulate this with dynamic imports, but then you'd have other issues).

This made me think of something else that I feel is important and I'd like to share with you. I quote tweeted Ingvar's tweet:

Ingvar expanded on what I mean (unknowingly I'm sure) in another thread:

Why pure modules?

Let's explore why this is a good idea. Consider the following scenario:

1// a.js
2import './b'
5// b.js
6import {serverData} from './c'
8if (!serverData.user) {
9 // redirect to login
10 location.assign('/login')
13// c.js
14const el = document.getElementById('server-data')
15const json = el.textContent
16export const serverData = JSON.parse(json)

The c.js module would need the index.html to have been rendered with something like:

1<script type="application/json" id="server-data">
2 {"user": null}

I expect this code would work in production as expected. There are a few problems I have with code like this (or in general any impure modules). Before we move on it's important to realize that before the console.log('ready') line is run, all the code in b.jsand c.js has been run first.

Unknown consequences 😮

When a developer imports the a.js module, it has no way of knowing what the consequences will be. If things aren't set up properly, the developer will see a cryptic message like:

1Uncaught TypeError: Cannot read property 'textContent' of null

and this because they simply imported a module.

Unnecessary operations 😐

Let's say that a.js actually only needs certain utilities that b.js exposes, and doesn't actually need anything from the c.js module to be run at all. In this scenario, those modules are doing extra work that is unneeded. Wasted effort that in some situations could be a pretty impactful depending on the circumstances.

What's especially annoying is when the wasted effort results in a cryptic error. Not only did I have to figure out what the error was all about, but I don't even need that code to run in the first place!

As a related (and very important) part of this, you cannot treeshake that unused code!

Inability to choose the order of operations 😡

What if I realize that c.js needs the JSON in the DOM and so I decide I can initialize that before c.js is required like so:

1// a.js
2const script = document.createElement('script')
3script.setAttribute('id', 'server-data')
4script.setAttribute('type', 'application/json')
7import './b'

Unfortunately this wont work because (per the ES modules specification) import statements are run before any of the code of the module regardless of where they appear in the code! Luckily they are at least run in the order they appear. So to do this I would have to create a new module for my setup code and import that one first:

1import './setup'
2import './b'

Impact on testing 😵

It's a pretty widely accepted fact that it's easier to test pure functions than impure functions. The same applies with modules. What if I wanted to test the b.js module? I'd have to initialize the DOM before importing b.js so c.jscan be initialized properly, but then how do I test it again? I have to do weird things with the module system to re-import those modules again after initializing the DOM differently.

With jest, you have jest.resetModules() which makes this much easier, but it's still not super simple, nor is it straightforward for anyone maintaining those tests.

The Alternative

So here's how I would rewrite things to be pure (in the sense that importing modules has no side-effects, though the functions they expose are not pure themselves):

1// a.js
2import {init} from './b'
6// b.js
7import {serverData, init as initC} from './c'
9export function init() {
10 initC()
11 if (!serverData.user) {
12 // redirect to login
13 location.assign('/login')
14 }
17// c.js
18export const serverData = {}
19export function init() {
20 const el = document.getElementById('server-data')
21 const json = el.textContent
22 Object.assign(serverData, JSON.parse(json))

How does this resolve the above problems?

  • Unknown consequences: We're importing the init method and calling that from both b.js and c.js, so we may not know exactly what those do without looking at the implementation, but we at least know that they're doing something. 💯
  • Unnecessary operations: If b.js exported additional utility methods, we could import those without running into any surprises. 💡
  • Inability to choose the order of operations: If we wanted to initialize the server-data in a.js then we'd just do that before calling the init method from the b.js module. ✌️
  • Impact on testing: We could easily run the initfunction from b.js in a test as many times, re-initializing the DOM before each test with exactly what we need without any trouble or hacks. 🎉

Note that the a.js module is not pure. At some point one of your modules needs to do something to kick everything off. This is the purpose the a.js module is serving. These modules should normally be very small (and often it'll be your index.js entry module).


Keeping your modules pure means limiting the amount of stuff they're doing at the root-level of the module. It allows you to completely avoid the issues mentioned and bring more clarity to your codebase. I hope these examples (while slightly contrived) have been helpful. Good luck!

Discuss on TwitterEdit post on GitHub

Share article
loading relevant upcoming workshops...
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.