Defining Isomorphic Javascript

A few years back I wrote a blog post analyzing design patterns I saw used historically and how that was going to change with the rise of Node.js. The title of that post was “Scaling Isomorphic Javascript code”, in which I did very little to define what “isomorphic” meant just in the same way that George Lucas did very little to tell you why two downtrodden droids ended up stranded on a desert planet yelling at each other.

Now more than three years later, I hear or read the phrase “isomorphic Javascript” almost daily. That rise in accepted usage has more to do with everyone else than it does to do with yours truly. Yes, I did my part fighting off the Hacker News trolls who called blasphemy for repurposing a mathematical term for Javascript programming, but the actual number of “isomorphic” libraries is staggering. Here are just a few of them that are out there:

So then what is my purpose herein? You might think of it as the portion of my original post that I left out. Namely: just what is Isomorphic Javascript?

First let’s get out our dictionary and see what we’ve got for the scientific and mathematical granddaddy of our present-day vernacular:

iso·mor·phic (adj.)


  • a: being of identical or similar form, shape, or structure
  • b: having sporophytic and gametophytic generations alike in size and shape

2) related by an isomorphism

Clearly 1(b) is not applicable because as much as we wish it were so, computer systems are not biological. This leaves us with the possible definitions:

  • “being of identical or similar form, shape, or structure”
  • “related by an isomorphism”

Now you might think that the first definition is the de-facto since it is “running the same code on the client and the server”, but in fact many libraries have some distinct similarities when running in the different environments. It is for this reason that we should prefer the latter definition of “related by an isomorphism”.

And at this point your eyes glaze over and tell me to go back to my PhD program in discrete math. I don’t actually have a PhD in Mathematics (embarrassing!), but I can still give you a little more context into what exactly an “isomorphism” is. Crossing the boundaries of math and programming is the problem of “screen to world coordinates” and vice versa. In a 3D game, there are all sorts of (x, y, z) coordinates that need to be mapped onto your 2D screen which has (x, y) coordinates. These two coordinate systems are isomorphic via the screen-to-world(x, y) and world-to-screen(x, y, z) functions, which together make up the “isomorphism” that relates them.

In this context, the isomorphism needed for an isomorphic library is related to the semantics of the code itself. You see, these semantics are similar (but not exactly the same) when running either on the client or the server. In many cases they may be exactly the same, but they need not be. The isomorphism is the thing that mucks around with the code to make the two use-cases sane. Take for example, one of the first isomorphic libraries that I wrote: director. Director is a routing library that works for client-side routing and server side routing (both HTTP(S) and CLI).

Yet the semantics of these routing functions are very different. Routing to a POST event in a client-side page makes little to no sense. Nonetheless, I refer to director as an isomorphic library, because there is an isomorphism that relates the two of them. This isomorphism is namely the client-side build script, which takes exactly the methods we need from the larger HTTP(S) / CLI implementation and packages them up into the browser-version.

Simple right? I thought so when I decided to repurpose our friend complex math terminology for complex programming terminology. At least it’s better than a new TLA or FLA because those don’t MEAN enough yet. I hope this has been somewhat educational and I’m looking forward to seeing more isomorphic libraries come out!