MDX in React-Native!?

Hi, I'm Daniel, a freelance full stack JavaScript developer from Finland. My definition of full stack is that I build web apps from scratch to production, meaning the UI and the styling thereof, back end with node, API integration, databases, servers, you name it.

I also build React Native apps and I continue to be amazed at how well my existing web experience can be applied in that area. It's such a normal thing to use a JavaScript or react specific library in React Native that instances where it isn't possible stand out.

Ah, good old NPM, the holy land of JavaScript developers, where I can usually find a package for whatever I need to do. NPM provides nice reusable solutions for sole challenge so that I can focus on the business logic, you know, what the app actually needs to do, without getting into the weeds of developing custom state managers or routers or styling solutions or whatever. But what if the thing you need doesn't exist on NPM? This is a talk about something which I took for granted to exist, but was rude enough to not exist. The solution I developed, and the challenges I ran into along the way. And of course, I put it on NPM.

MDX is in the title of this talk, so what is MDX? It is a combination of two technologies, Markdown and JSX. I realize these two may be very familiar to this audience, but let's take a look at the strengths they each bring to the table, and imagine what a team might look like.

Content is king. And the ability to create and display content is hugely important for any application. If your content is text-based, Markdown is a great tool to use, as it provides everything you need while being very simple and easy to pick up for anyone. With Markdown, you can write formatted text anywhere that accepts keyboard input. You don't need specialized word processing software for that anymore. Markdown is readable for humans as it is, but to actualize that formatting, you just need a Markdown renderer. Markdown is standardized, and has been around for a while, so there are lots of libraries available for probably all programming languages and platforms. Markdown is almost as easy to render, at least to write, due to again, being just plain text. Nowadays, we expect Markdown to be supported, and it feels as if that just happened overnight. One day, we had as many formatting languages as there were apps with text areas, and the next day, Markdown was everywhere. Of course, people have worked hard on this, but it shows how important it was to unify and standardize these simple formatting features and how badly it was needed.

I probably don't need to go into why React is great, since I'm speaking at a conference called React Advanced, but I do want to touch on JSX, which React introduced and popularized. Whereas Markdown simplified text formatting and made HTML unnecessary for these use cases, JSX takes HTML to the next level. When I got into programming, mixing HTML and JavaScript was a no-no. It was taboo, since these were separate concerns. You had your HTML, which you decorated with styles and scripts. Never the twain shall meet. When I first saw JSX, it was horrifying, since it went against everything I had learned until that point. But I took the leap and tried React.

And I haven't looked back since. JSX enables declarative code and a composition-based architecture, where the structure of the application is involved in the business logic as a first-class citizen, rather than something separate and disconnected, which you need to surgically modify in order for it to reflect the current state of your app.

HTML is static and is by itself not enough for modern applications. Attempts have been made to make it more dynamic, some more successful than others. Server-side HTML rendering does work quite nicely, but once the markup arrives in the browser, it is still static and asking the server to do updates which the client could do much easier and faster is a user experience that smells and tastes like the 90s. And when you try to manipulate static HTML with JavaScript or JQuery, it quickly turns into a game of Jenga with way too many people moving blocks around simultaneously.

In contrast, JSX makes it easy to compose self-contained components that include the logic, styling and layout that they need to accomplish their task. The UI is a product of the state and not something the developer needs to attend to separately. UIs can be quite complex without it all falling apart.

MDX is what a combination of these technologies looks like. Instead of only having bold and italic, and maybe something else, you could have any effect that you can do with CSS and JavaScript. MDX really busts the floodgates of possibilities wide open. It's great for blogposts where you can add a demo in line with the text or use special highlighted text. Josh W. Como's blog is a great example. It talks about how he built it here.

And in fact, this very presentation is made with MDX. I borrowed a sparkly text effect from Josh's blog, dropped it right in, and it just works. But that's only scratching the surface. MDX makes it possible to serve any interactive content through, for example, a CMS, as easily as serving text, making it possible for any writer to compose engaging multimedia content using components that the dev team produces. It looks like this. It's mostly just markdown, but what's that? A React component in the markdown. Yes. This example is kind of simple. We can, of course, do any React component, like this video player. Here's Jay Foreman explaining the boroughs of London. It's a great video, but let's watch this later. We can do a 3D scene. This is from the React 3 fiber examples. Again, I dropped it right in, and it just works. The possibilities are endless. At least for the web realm.

But what about React Native? So, I'm developing an app with my dad, who's a writer. And MDX is the perfect technology for bringing his content to life. And making it interactive for users by weaving in engaging widgets and special formatting. I went forth to install the MDX library for React Native from NPM into our React Native app. MDX is React. React Native is React. So, surely it exists, right? It didn't.

I did some research, and the best way to use MDX in React Native is to use the MDX runtime. Which as the name implies, runs whatever you give it like the markdown and React components at runtime. This is theoretically platform agnostic, as it needs to be fed the markdown components that it should use. It comes with a huge flashing caveat, that it runs whatever you give it at runtime. This thing should not be anywhere near user-provided input, unless you enjoy getting hacked. For my use case, I'm only going to feed it my dad's writing and my own React components. Unless my dad really wants to flex his hacking skills, the risk here is pretty low.

So, to make MDX on React Native a reality, I first needed to make markdown on React Native a reality. MDX is primarily designed for web use and renders the markdown into whatever a p, strong, or h1 tag is. React Native has no clue what to do with that. Creating these components was probably the biggest challenge I ran into during this endeavor, since MDX can be tricky with spacing and React Native styling can be tricky overall. I had to battle with cases where the line of text got cut off vertically and an inline component affected the line height, among many other issues, memories of which I have repressed. I needed the components to look the same, in addition to good, on both Android and iOS. I used the React Native markdown renderer library which includes native markdown views as a starting point, and cobbled together native components for most markdown features.

Finally, MDX in React Native! As we've established, there were no ready to go packages, so I put my first solution up as a gist. We did finish the first version of the app with an MDX solution with an MDX solution largely based on what I published in the gist, but we still have much more ambitious plans for it.

After a lengthy code break, I continued developing the app and wanted to improve the MDX features specifically. Surely, after all this time, someone else had also needed MDX in React Native and made a more polished library? Nope. After a few years, the search results for React Native MDX looks like this on Google. On DuckDuckGo. On Brave. And I even went to Bing. My quickly thrown together gist is still the best way to use MDX in React Native.

After waiting for someone to create a solution, I now realize that someone was me this whole time. And the world is ready for a proper and polished MDX library for React Native. Introducing RnMDX. Some elbow grease later, and it is, indeed, real. It can be dropped into any React Native app, including Expo apps, and render interesting and interactive content composed by editors, designers, and copywriters. The goal of RnMDX is to deliver ready-to-use React Native markdown components and allow the developer to focus on their custom components, which they want to use in MDX, without needing to worry about the markdown part. Then it either renders MDX content on the fly, with the MDX runtime, or pre-compiles MDX into JavaScript with the RnMDX command line tool. Rendering MDX with the MDX runtime is the easiest way to deploy MDX in React Native, and RnMDX makes it even easier by providing working and sensible markdown components integrated with MDX. You don't need anything else, just get the MDX content as a string from somewhere and throw it into the runtime. Of course this carries additional overhead, and it is very insecure. The runtime will execute the string that you give it, mounting and running the React components within it. So you need to make sure that it is trustworthy and won't get up to any funny business. I can't in good conscience recommend using the runtime, but if you can be sure about the trustworthiness of the content and don't mind the extra overhead, it is definitely the easiest way to go.

On the other hand, if you want to go by the book, you can precompile your MDX into JavaScript and use it in your app like any other component. This is, of course, more complicated, but it works much the same way as a React-based static site generator like Gatsby. The core of the RNMDX library is the collection of Markdown components that you need to fulfill the MD part of MDX. Continuing from the components I published in the gist and used in the app that started it all, I spent more time on them to make sure that all Markdown features are covered and that they make solid building blocks for any use case. It's also possible to override any of the Markdown components by providing your own implementation and assigning it to the key of the MDX feature that needs some special care in your particular application. As for styling, the Markdown components can be styled with good old React Native stylesheet objects or any library that extends them. And the styles may also be overridden by the user, just like the components. The Markdown components under styling was one of the challenges with creating this library.

React Native can be finicky at times, so there are some common issues with Markdown content that I want this library to provide solutions to out of the box. Spacing, line height, and font size, where the pixel size looks different between Android and iOS, are just some of the challenges. Now, I'm pretty good with CSS, but this is what it felt like. Making all Markdown components look their best on both platforms out of the box is an area that has, and probably will, continue, require continuous adjustments.

And as stated earlier, the right way to use MDX is to precompile the MDX into React Native components and RnMDX provides the command line tool and all other facilities that you need for this workflow. Precompilation of remote CMS content is, of course, also possible. It is crucial for any kind of content application, after all. Since we are working with native apps, this kind of static precompile workflow isn't as smooth as it is in the web world with, for example, Netlify, but it is viable using CodePush or Expo. So, what you need for the precompilation workflow is a config file that tells the RnMDX tool where the content can be found and where the compile components should end up. I'm still working on this workflow, and all input on the subject is welcome.

So, how does RnMDX look in practice? I'm glad I asked. Here is a simple app using the runtime method. Let's look at the demo. Here we have a very simple app. It's an expo app, and I have imported RnMDX. The render MDX component here takes the custom components that you want to use in your MDX and the MDX content as a string. Then it just renders them into native views. On the right, we have the MDX content that we are rendering. There's the color text, which is an inline component that wraps text. And then, we have color box, which is a block level component. We can give them props like normal React components, and the result is here. Ta-da! Very simple. The red text according to the prop value, which is red, and then different colored boxes according to their prop types. So, it's very simple, it's versatile, and you can use it for pretty much anything. It doesn't impose a lot of restrictions that MDX or React Native doesn't impose.

So, without further ado, let's get back to the presentation. MDX now exists on React Native. Great! Now what? What should you actually use this thing for? The short answer is, whatever you want. It's another tool in your toolbox. You could serve the whole app layout from a CMS as MDX files if you want, but the first sensible use case that comes to mind is an interactive online magazine or blog where the web version runs on Next or Gatsby and you already have a bunch of MDX articles with cool React components.

If you want to bring them into your native app, that is now much easier. You would, of course, need to make the components React Native compatible, but after that, it is just a matter of pointing your native apps towards your CMS and show the articles in all the glory in a mobile app.

Mobile apps aren't really the best medium for long form text, though, but that doesn't mean there are no opportunities to use MDX outside of magazine apps. If you have a chat bot-type interface, the discussion can now involve any React component you implement. Anywhere there is text, there is at least an opportunity to add some original styling.

It's easy to take npm libraries for granted. How often have you not found something you needed? It is a truly remarkable resource and I want to sincerely thank everyone who contributes code and more importantly, time, for the good of the whole extremely large community. This is not my first npm package but it is my most ambitious one yet. I'm actually quite surprised that it didn't exist. So the next time you don't find something you need, consider contributing your solution. Turns out you were the one meant to do it all along. That's it for me. Thanks for watching and I hope you find RNMDX useful.