React Advanced

React Advanced Conference 2021

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 challenges 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. And 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 blog posts 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. He 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. And 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. And 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 largely based on what I published in the gist, but we still have much more ambitious plans for it. After a lengthy COVID break, I continued developing the app and wanted to improve the MDX feature 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. The world is ready for a proper and polished MDX library for React Native. Using 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 precompiles 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 to 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 command line tool where the content can be found and where the compiled 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 renderMDX 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. So 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. And 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 their 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 chatbot 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. I know I will.


Daniel Dunderfelt

React Summit

React Summit 2020

Smoothly Inclusive Component Library Documentation

♪ Hello, my name is Kathleen McMahon, and I'm here today to tell you how Gatsby and NDX makes your component library documentation smoothly inclusive. Before we begin, let's get some details out of the way. My slide deck will be posted unnoticed, including links to resources that I briefly touch upon. The full URL will be available later today on Twitter. But for now, if you want to download, if you want to take a look, you can look at https://noti.st/.resource11. You can also find me at resource11 on Twitter, Instagram, and GitHub. Before we dig into Gatsby and NDX, let's back up a bit so I can introduce myself a little bit better. I'm a principal engineer at CarGurus, and I race bikes very badly. Mostly you'll see me in costume racing two laps to your six at the back of the pack on a single speed bike. Mostly. Unless something happens. Like a pandemic kicking in our doors. Then your racing season is postponed. So while I'm an engineer and a super slow bike racer, I am a super fan of design systems, especially the component library parts. Before CarGurus, I was a tech lead for the O'Reilly Media Design System. While I was there, I learned a lot about streamlining component libraries and optimizing documentation. If you've never worked on a design system before, let's just say there are a lot of moving parts. And if your core team is small and you are rebooting your component library, you really have to choose your focus and rely on your contributors. In our case, our focus was to extract the business logic out of our components and get the accessibility in. We fixed our colors, our components, our patterns, and rebooted our docs. Once that was done, we realized that part of our system was becoming a hindrance to our team and a barrier to entry for our contributors. Our documentation. Our process was spread across two projects, the design system repo and the design system docs repo. In the design system repo, the documentation content was stored in two locations, while the docs repo held the site scaffolding and the docs layout components. To get up and running, you had to follow a detailed series of steps to sync, run scripts, grab files, parse information, generate data, and render the docs into a React app. That's a lot. Just getting started working with these repos was overwhelming for new contributors, to say the least. And there was more. The scripts were set up in such a way that you had to write your markdown in a very specific order for your component and your content to show up in the docs. Your button heading could be paired with an intro paragraph, but only one paragraph. Same with the variants, only one paragraph, and then a code block. Best practices had to be written as an unordered list, always. Same with the related component section, always an unordered list. So while our docs scripts were great for generating color swatches and details about which props were available in components, the process was not great for creating our component documentation. Which frustrated everyone. One mistake and if not whole chunks of documentation would be missing from the component pages. We had the freedom of using markdown, yet we were not taking advantage of it. This was a serious cognitive lift, even for someone who was very familiar with the code base. Now imagine if you have a new contributor to your project, not exactly a welcoming experience. We decided to review our process and see what wasn't working. One of our biggest issues, we chose to show one component variant at a time, rather than all at once. This forced our users to access a select menu over and over again to compare component variants, which increased the time they needed to look up information. It didn't make sense. In retrospect, that decision was about as questionable as a recipe that combines Jell-O with shellfish. So we decided it was time to make our docs contribution process more user friendly in terms of structure and in terms of how we authored. Especially the component example pages. We wanted the users to have the confidence that whatever content they wrote on the docs page would make it into that docs page. If we made our docs more user friendly, we'd have more contributors rather than fewer. We considered our options for making our docs better and decided upon Gatsby for a few reasons. One, Gatsby gave us a way to migrate all our main documentation pages right into the site without much fuss. Two, Gatsby provides a web pack and Babel config similar to create React app. So we could start with a scaffolded project and extend as needed. And three, Gatsby supports MDX. So we could write component documentation using Markdown, import React components right into the file, and it just works. Even better, MDX compiles down into semantic HTML, which in turn gives the site improved accessibility. Better support for users that rely on assistive technology to access the docs. If a design system is promoting inclusivity in general, it really should. It follows that inclusive docs make sense. As a bonus, Gatsby restreamed our site from two repos to one and reduced the amount of CLI commands dramatically. The default setup for Gatsby is great. However, we needed to make some adjustments so Gatsby worked for our needs. In the Gatsby config file, we added Gatsby plugin post CSS to support post CSS. Gatsby plugin compile ES6 packages to support our design system package. Gatsby plugin MDX so the site would recognize MDX files. Gatsby remark auto link headers to generate auto links for page headings for better screen reader and keyboard support. Gatsby plugin page creator to create pages from the source pages folder. And Gatsby plugin file system so we could pull in our data file and point Gatsby to the folder where all our component MDX files lived. In the Gatsby node file, we added a GraphQL query to find the component MDX content and a create page action to route and pages for the component docs. In the Gatsby browser file, we added things we wanted to apply throughout the site, like our global CSS styles and the wrap root element component. The wrap root element component acts as a wrapper around the site's root element and imports the MDX provider. This way, the entire site would recognize MDX content. We had to do one extra thing for our component docs page template, though. Since our component MDX files were located outside of source, MDX renderer was needed to wrap the contents of our component page template. Otherwise, MDX files would render like this in the browser. Now that our layout template used MDX renderer, our component MDX pages would render as we want in the browser. Now we could pop in React components next to code blocks in our MDX, and they would render, no problem. We could even wrap a button component with a display box component and add a more cohesive look to the component code block pairing. If we wanted to add a props table to show which props can be used with the component and created a component that pulled in data to render as a data table of a props table component, pop that component into the docs MDX file, I can speak today, passed in the name of the component to render, voila, the docs would show a props table. For our component dos and don'ts, we used to have to write out an unordered list in the markdown file. And the links and the list rendered like this. With MDX support, we instead created a custom component that renders unordered lists. We could pass in a dos list and a don'ts list array into that component. And boom, a nicely styled dos and don'ts list. Code blocks. Markdown has great code block support. MDX makes those even more powerful. So we were psyched to add this feature. You can override the styling of a code block in an MDX file with a custom code block or even display different types of code blocks. You can use Prism React Renderer in a custom code block component and import a theme with good color contrast like Sarah Drasner's night owl theme. Then you can wrap your code block and theme it, import that code block component into your wrap root element along with the pre-code block utility, and override the default pre-tagged styling at the app level by passing it in as a component to the root wrap element. So now when you write a code block in MDX, instead of the baseline styling, the custom code block will render with syntax highlighting. Fun fact, you can pass in a prop to that code block and do really cool things if you use custom code blocks. For example, if you abstract this MDX into a dryer pattern in our custom code block component and pass the display box prop into that code block, if you add the display box prop to the code block in MDX, you'll get a code, you'll get a display box paired with a code block. Now, what about if you want your code block to be an editable code block? You can add a React live option to the component and show the component inside a display box pairing with an editable code block. So if you add the React live prop to your MDX code block, you'll get an editable code block and see your changes in real time. So if we write something like this, where we have three code blocks in MDX, one with the React live prop, one with no prop, just the name of the language, and the third one with the display box prop passed in, this is what you will see. So over here is I comped up a quick MDX file in my blog site to demo. If you pass in, this one is the JSX with the React live prop passed in. This one is with just JSX passed in as the code, and this one is passing in the display box prop to the JSX code block. What is great about the one with the React live prop is we are combining the display box fanciness and the block here, but this is now editable. So I can do things with it, and if I know what props my component supports, I could make this button. If you look at there, it actually has error handling, but small button, wow, and I could also, I know I support icons, so the icon I could use is the right arrow, because I'm using React font awesome components under the hood. Look at that, I just added a icon to my button, but this, adding this type of editable block, editable React live support to your code blocks is very powerful, because your developers will be able to go into your component, into your documentation, and play with the properties right there and understand how to use your component right away, versus having to try, you know, look through all your props tables. This is another way for learners that need to type things to see how things break. So editable block component, editable code blocks are amazing. Now, I'm going to go back to the slides and wrap this up. So, to wrap up, if your documentation setup is brittle, your contributors will flee. But Gatsby and MDX helps make your docs inclusively smooth in both setup and execution. And your contributors will return. And they will be happy to be part of your team. Thank you. ♪♪♪


Kathleen McMahon

The X in MDX

♪ Let's start with this Markdown file. I'm assuming we all know Markdown. There's a reason why it's so popular. It has a very clean syntax. I'm sure I'm not the only one who likes to move as much content as possible to Markdown. Even content that doesn't originally belong to Markdown. And that's why we have MDX, right? We had to extend the original format so we could put more things on it. In this talk, we'll take this to the extreme. We'll use MDX for more unusual content and layouts. But first, I need to show you how this works. We're going to start with this small React app. This is using Next.js, but the same applies to any app that has the MDX loader. Most of the magic comes from this import. Here, the MDX loader transforms the Markdown file into a React component that we can use anywhere. And you can see it renders what you expect here on the right. If we want to change what's rendered, we can use the MDX provider component. It has a component prop that lets us override any of the default components. For example, here we are changing all the H1s and adding a purple border. A special component we can override is the wrapper. The wrapper is the component that wraps the content. Here we are just adding a border to it. But the cool thing about this component is that in the children prop, we get all the content from the Markdown file as React elements. React elements are just JavaScript objects. Here you can see what's inside the children prop. We are rendering the wrapper children as JSON and filtering some properties to make it easier to read. You'll see that it is an array. The first element is an H1, the second a paragraph. Each element comes with an MDX type. We will use that MDX type to extract information about the content or to change the elements. For example, we could get a list of all the H1s from the children and render it as a table of contents. This is a simple example, but it illustrates the pattern we are going to use on the rest of the examples. In all of them, first we extract some data from the children and then we render it in a specific way. Keep in mind that this runs on every render. In most cases, it isn't a performance problem, but if it is, you can move it to a plugin and run the transformation on build time. I usually write content that has steps, like tutorials or any type of walkthrough where you explain something step by step. Markdown doesn't have any specific syntax for grouping things in steps, but we can use MDX to extend Markdown and introduce our syntax. The implementation of the step component we are using here doesn't matter, we are just using it for grouping elements. If you are new to MDX, this may not be the best introduction. The typical use case for MDX is embedding interactive components in Markdown, but here we are taking a different approach and using it more as a syntax extension for Markdown. Now, based on the MDX file that has steps, we can write another wrapper component. In this case, in the children prop, we get one React element for each step. So we can keep track of what step we are showing using React state and let the user change the current step with a button. Ok, now I want to show the same content but with a different layout. There is a technique called scrollItaling, you might have seen it on some websites. As the user scrolls down, there is some part of the layout that sticks to the screen while the rest scrolls away. So let's do that. Since this is a lightning talk, I'll import the scrollItalingLayout component. I'll share the link to the repo later if you want to see how it works. The scrollItalingLayout component takes two props, one for the left side that can be scrolled and the other for the sticky part on the right. When the user scrolls to a new step, we show the corresponding element from the sticker list. Now, instead of showing the step number, let's add the sticker content to the MDX file. Suppose we want to show some code in the sticky part of the layout. There isn't any specific syntax for this, so we need to create our own convention. Like for example, we put the sticky part of the step as the first element. Now, doing some array transformation, we get the list of steps and the list of stickers and pass them to the same layout component. So when the user scrolls, the code on the right should change accordingly. Just for fun, I have a terminal component that animates between code transitions, so we can use it for the stickers. I've been experimenting with another layout for walkthroughs. Instead of changing the steps using the scroll, like in this example, we can synchronize the steps with some media, like a video or an audio, maybe a podcast, and change the steps as the media progress. To do that, in the MDX file, we need to specify the media file and the time range for each step. Once we have that, we can extract the information from the children on the wrapper and pass it to another React component. This time it's the TalkLayout component that will solve all the syncing for us. And you should see the steps changing every time I snap my fingers. Some of you might have noticed that this looks similar to the layout of this talk that I'm giving right now. And it is! This talk was built using the same technique. It's all MDX. For example, here on the left, you can see the code for the steps you are currently watching. And here is the next step. And that's all. That's all I have. The takeaway is you can use MDX to build your own dialect tailor for any specific layout. I leave you here the links to the repo of the talk. Not the slide, but the talk itself. You run Yarn dev and you can watch this talk again. Also, there's my Twitter and the components we used. Most of them come from a new project I'm working on. It's called CodeHike. And it focuses on code walltrusts and tools for making it easy to explain code. Thank you.


#MDX