Avoid self-inflicted MDX lock-in

Let's not beat around the bush: we can't all be Josh Comeau. The craftsmanship and attention to detail that go into his blog is just something else. No wonder why people (or at least me) get inspired by it and try to adopt a similar format. The perfect tool for this format is MDX: a joint venture of Markdown and JSX.

Well, then let's bring it in. What's the worst thing that could happen? We are just making one step away from a regular blog, sprinkling in some interactivity, right? In reality, it's rather a leap towards a full-blown web app and you may not be prepared for the cost of maintaining it.

Just a blog

Consider a fragment of an exemplary stack for an interactive blog:

  • JavaScript framework (e.g. React) - to create interactive components.
  • Meta framework (e.g. Next.js) - to provide the server-side functionality.
  • MDX tooling (e.g. MDX.js) - to parse and render MDX files.
  • UI library (e.g. Chakra UI) - to give you a headstart in crafting interactions.

A child putting a jenga block

I detailed these specific dependencies for a good reason: you update them frequently and they are not always compatible with each other.

Imagine this stack is a physical jenga blocks stack. You can be tempted to visualize adding a new piece to this stack as placing it gently at the top. It leverages the built foundation by standing on it with confidence, while not affecting much else around it.

In reality, the blocks can be much more intertwined. Sometimes the new block goes in the middle, and sometimes even at the bottom of the stack. If you are lucky to actually put it at the top, you can not be sure that new blocks will not come in at some point and cover it.

Keeping Up with the Codeashians™

Over the last year, we have had a number of transformative moments in the React ecosystem: the advent of Server Components, the uncertain future of CSS-in-JS libraries, the latest release of Next.js, and so on. For many applications, it was a time when the blocks crumbled.

Before I write my blog post, I want to use this new Next.js feature. But I can't upgrade Next.js, because it breaks my UI library, it doesn't support it yet. Maybe I just remove the UI library altogether? It looks so 2010s anyway, I can do better with plain CSS. But what about the interactivity of the components? Do I want to rebuild that from scratch as well? Nah, I don't have time for that. Wait, what was I doing again?

In a commercial environment, maintaining the stack is included in the overall cost of building software. Worst case scenario you spend a day or two fighting the dependency upgrade. In the end, you are paid to do so.

If you treat your blog as a technological playground, the struggle of keeping up with all the updates may be a welcome challenge. However, if you just want to focus on creating the content, you are in a pickle. You seem to have two options: skip the updates and risk your website becoming outdated or invest into maintaining the stack for the cost of the time you could spend on writing.

No wonder why a surprising (because you are a developer, you develop things) third option reveals itself for many people: pay for a blog platform. There is a number of excellent ones that allow you to focus on writing and take care of the rest, like Hashnode, Ghost or Medium.

JavaScript lock-in

If you already have a MDX blog, beware that migrating somewhere else will not be easy. Markdown is a universally accepted format, "just text" that can be parsed and rendered the same way everywhere. The addition of JSX breaks that standard and you are now on your own. In this situation, you either find a static replacement for your MDX components or you remove them completely. They become a dead weight.

You can end up in a pretty ironic position: you wanted to build your own blog to avoid the vendor lock-in, but you ended up locking yourself with JavaScript.

I painted a pretty grim picture of maintaining a MDX blog, but I don't want to discourage you from building one. I want to make sure you are aware of the potential costs involved. Trust the guy that just paid these costs and is not looking forward to paying them again any time in the future.

If you are considering building a blog like that, I can offer a piece of advice. First, think about the content you want to be publishing. Then, think about the content you are most likely to be publishing given the time you have. When you want to build an interactive blog, remember it's not just a blog anymore. It's a web app. And web apps require more maintenance than just a collection of text files.