From Architecture to Adoption: Engineering & Scaling a Modern LMS with React

Hi everyone. How are you finding your time in Amsterdam so far? Good? Perfect. The weather is nice. So that's always amazing, especially for Amsterdam. But yeah, before I introduce myself, I wanted to ask you a question. I was wondering if at some point in your career, you had to learn something that your boss or your project manager asked you to do really fast, like fix that bug or implement that feature within your platform? You had to do something like that very quickly, right?

So the next thing is that I'm assuming that you then went through the docs, watched some YouTube tutorials, or even if you were really stuck on it, maybe bought a course. But I'm assuming that what happens for me typically when I try to cram all that knowledge in about a week, we typically forget what we've learned. So that happens to most of us, it is completely normal.

So my thought is that it is no wonder that that happens, considering that most online learning platforms feel almost identical. There's a video, there's some text beneath it, and a comment section that nobody seems to reply to. There's YouTube as well, which is amazing for interactive content, but it's more or less the same thing. Video at the top, some description then, and then comments. And as developers, we're used to interactive docs, especially nowadays. A lot of these DevTools are creating docs that you can actually move around through and select your options for technologies and things just work instantly.

There's also Stack Overflow and Code Sandboxes. We learn by doing. And most learning platforms still haven't evolved to support that. And I mean, it's no wonder, I get it. Imagine a platform trying to support somebody trying to learn how to play chess, maybe bake sourdough, coat in rust, or raise a petiguana all at once. You just can't do it all. So that is because you would need to accommodate for all of these different types of learnings. You would need a baker to assist to throw a live chat, a chess board widget, syntax highlighting for every language ever made, and Terrarium Simulator, I guess. So there's a lot of stuff that you would need that a single platform can't do it all. I think we can all agree with that, and they shouldn't. Not a single platform should cater to every single audience.

So that's why I think that we need a learning platform made for developers. So, hi there. I'm Adrian, the founder of JavaScript Mastery, where we educate, thankfully now, millions of users worldwide through project-based YouTube tutorials. And today, I want to share my take on building that learning platform. And not just how we build it, but I want to share some real-world case study of how we are approaching it.

The architecture, scalability, performance, obstacles we encountered, and then retention, how to actually keep users to come back to the platform every day. And honestly, most of these lessons that I'm going to go over today apply to any content-heavy app. It's not just learning management systems. It's not just CMSs. Anything where you have to manage a lot of content, some of the things that we're going to go through today, you'll be able to put to use.

After struggling with trying to use different LMS platforms, again, they all fell into the same cookie-cutter design, I wanted to build content the way that I build apps. Flexible, modular, reactive, if you will. So, do you think that there is a specific format that would allow us to achieve that level of flexibility with code? Maybe different kind of text formats, like Markdown. Markdown was, of course, the first thing that we tried, but it still felt a bit too limited. No interactivity, no logic. More like a blog post.

Then, we tried different CMS platforms, which were better, but still no native ways to embed interactive components or add some state into the lessons that people are learning. Then, I gave MDX a shot. It's Markdown plus JSX. Can I get a raise of hands of how many people have heard about or used MDX before? That's about half, I would say. Mostly for blogs, I'm assuming, right? Most of you maybe have your own blogs running on MDX or documentation pages, docs. Yeah, it's a lot of docs. It's an amazing technology that allows us to basically inject real components anywhere. In our case, for a learning management platform, that's quizzes, call outs, assignments, video players, code sandboxes, all live, interactive, and context-aware, which is a completely different story than just having a video and a piece of text.

MDX helped us with that. Suddenly, content creation felt more like coding because I could embed any kind of custom component, or if it didn't yet exist, we built it in React and then used it within lessons within the MDX structure. Is that it? MDX solved everything? Thank you for coming to the TED talk. Well, not really, of course. We quickly hit walls with scalability. Why? Because we were managing all of these markdown files locally. I had dozens, if not thousands technically, of individual MDX file lessons that we were storing locally. Whenever I wanted to reuse a lesson in another course, I had to copy and paste it. Not really an intricate system that will allow us to reuse specific lessons or content. Things very quickly got pretty messy.

Files multiplied, app size grew, and the developer experience was out of the window. We decided to re-architect everything. Instead of files and folders, we started thinking in terms of entities and relations. First, I moved all the MDX files out of the repo onto the AWS S3 bucket, which made the content updates independent from deployments. They're fetched on demand and rendered at runtime, not at build time, because when we had them locally, the builds were taking so long to go through. Then I built a simple model of how we can structure all of those lessons. The most little piece is the MDX file, and we're calling that a content piece, which is just an individual file stored in S3. Then we have modules, which are essentially collections of content pieces, and then courses, which are collections of modules. No more duplication. Courses could reuse modules, and modules could reuse content pieces. So instead of copy-pasting content everywhere, this gave us true reuse. Like component composition in React, but for content.

Then things were pretty simple at that point, but I decided to take it a step further by developing something we call learning paths. The way that they work is that users take short surveys and share what they want to learn about and at what stage of their learning path are they right now. Based on that and their desired tech stack, we then can programmatically generate custom paths, mixing everything we talked about so far, individual MDX lessons, modules, and courses, all together to form a linear learning path depending on the user's current state and where they want to go. If you think about it, it's all about composability in React. Just like in React, we could reuse, override, and avoid any kind of duplication. The takeaway here is that you should treat content as structured data, not as static code. And again, this is not just applicable to LMSs, this is applicable to any kind of a content-heavy application. So at this point, the architecture felt simple, it finally made sense, but that took a lot of iterations to get it right.

But we were finally at a stage where it felt right. So let me tell you a bit more about how the architecture worked and how it felt. Everything lives inside a monorepo. So we decided to use a monorepo structure managed with TurboRepo, which really gave us an amazing developer experience with build caching and shared packages that we could reuse. Reuse where? Where we'll split it into two different parts. The admin side for analytics and content creation, and user side for browsing, learning, and progress tracking. So we were able to reuse these different pieces of UI, as well as logic, across both platforms within this monorepo.

The core stack is of course, React 19. But as a full stack framework for React, it was Next.js in this case. Then Postgres as a relational database, Drizzle ORM for schema modeling, TRPC and Zod for full type safe APIs that allowed us to bridge between two different parts of our monorepo. And then Tailwind and the chatCN for shared components. This stack might feel familiar if you already heard about the T3 stack. How many of you have heard about this stack or used it or used at least some pieces of this stack in your apps? Okay, I can see some hands right here. So it's fairly popular and it's amazing for quickly prototyping applications and getting them to market so you can test them and prototype them. In this case, for us with Zod and TRPC, that has been a game changer because we got full type safety across both applications with fast iterations and minimal glue code that we had to add to make it all work together. So it just felt right.

And this architecture allowed us to append additional features to the platform itself. It was very easy to add them. So one of the first features that solves the problem that I talked about at the start, which is the rigidity of the typical learning platforms, we wanted to add code sandboxes, which are basically like interactive playgrounds that you can add or now embed directly within individual lessons. This allowed us to have live code with no setup and no context switching. If we presented a video about something at the start, we could immediately then follow up on it and people were able to test it out. Learners were able to experiment with the code and see live previews directly within the lesson that they were learning. We also wanted to help users retain what they learn. So after each lesson, we generate a short quiz to allow them to just recap what they learned. And here, we used a bit of AI because, yeah, what would an app be without AI these days? But again, we didn't just add it for the sake of adding it. We used it where it actually made sense. So we fed it the video details and the transcript and asked it to then generate nice questions and present it to people instantly. This worked out incredibly well. People loved it. So we were seeing immediately about 1500 quizzes completed daily.

And it seems that users really enjoyed that quick recap after a 30-minute lesson. For analytics, we used PostHog. I think at this point, besides Google Analytics, it is one of the best developer-friendly metrics platforms. We used it to track everything. So we tracked clicks, events, custom events, session replays, a lot of it. And it quickly became overwhelming.

Just because PostHog allows you to add all of these different dashboards with metrics, we added every single one of them. We were working with a lot of pieces of data, but we went overboard. We could not make sense of that data because we collected so much. We eventually brought in a growth marketer who then helped us simplify and focus on these actionable steps.

Because as developers, maybe we should not focus on trying to do every single piece ourselves. Of course, if we get the opportunity to have somebody else within the company do it, we should be focusing on what we do best, which is development. Once we simplified the data, it started making more sense. So we were able to make more educated decisions on the types of features or types of content that we want to add to our application. And this was great.

So at this point, we have chosen our system of content delivery for as Markdown. We have made it scalable by hosting those files somewhere else and came up with a system that worked. And we also had analytics and all of these interactive platforms that are going to make it easier for future developers to learn about something. So clean UI, tons of features. It was working great. And since we have a large developer audience, we were kind of ready to put it out there.

We prepared some materials. We shared it across a newsletter. And people were quickly starting to come in. But once we hit deploy and shared the link, we waited. People seemed to love the idea. But then they said that it feels slow. When we tried to add so many of these features, we kind of put performance at the back side. We were just trying to cram it up with many features. But then, yeah, it turned out to be slow.

On my machine, it worked well. But once we tested it under slower networks, older devices, a reality hit. Landing pages, for some users, took about 10 seconds to load. Lesson pages, about 15, because they had that huge Markdown file with different interactive elements. It was embarrassing. These are very terrible times. But that happened because we tried to fit so many features without necessarily thinking about performance at the same time, which is something you should never, obviously, do.

Especially because Next.js, out of the box, and React nowadays, with React Server Components, gives you a toolkit of different things that you can immediately try to use to make the loading better. Like SSR, SSG, ISR, React Server Components, partial pre-rendering. All of these tools are at our disposal. But the choice of which ones should we use is not binary. Lydia held a great talk just before today, talking about React Server Components and React Compiler. And there's a lot of different things that we can do if we know how to use it properly. But my mistake was trying to render everything on the server side. SEO is going to be great. Load times should be great. But that was just not the case.

A lot of things were happening on the server, blocking us to return the data, and it just wasn't working well. So we have to be strategic about rendering the content, not just think about it in terms of client versus server. So we mapped it, or the components in the pages, by intent. So we server rendered the lessons for SEO benefits, so people can search through all the content that we create. We client rendered the progress, the comments, the search, and everything the user interact with. And then we fully statically render the marketing pages.

On top of that, we also added a lot of different strategies to further improve the performance. We added React Suspense Boundaries to split the rendering into async islands, so maybe we can show something at the top, while the rest of the part is still streaming in. That also helped a lot with performance. We used React 19's useHook for progressive hydration with no layout blocking. This further improved the performance. A bit of React's cache method, which allowed us to memoize the heavy functions, especially the ones that are like fetching the user progress, which is very heavy and takes a lot of time to fetch for all the different kinds of users. So that also helped with performance.

Of course, we optimized the assets, turned every single single wire PNG or JPEG into a WebP, and preloaded the ones that appear above the fold, and then lazy loaded the ones that appear below the fold. Some things that we should do before we go live in any kind of an app. We also disabled Next.js' prefetching to avoid downloading huge pages preemptively, because our MTXs had a lot of links within them and the platform was super interlinked. Behind the scenes, Next.js was prefetching a lot of stuff, so we had to disable it. And then later on, maybe we're going to do intent-based prefetching instead of just prefetching everything.

The result is that we went from FCPs of 4.6, so the first Contentful Paint, once something appears on the screen, and largest Contentful Paint from about 8 to 10 seconds. And very, very high bounce rate, because developers are, if we're going to be honest, are very tough crowd and they want things to load very quickly and to work smoothly. So a lot of people were just leaving the site without even trying to sign up. And that's okay. It makes sense, right? We went to about 0.5 seconds on FCP, 1.5 seconds to LCP, and the bounce rate dropped significantly, which means that people were more engaged with the app and using it more often.

Which I think is a great lesson. We all know about it. The faster the app is, the bounce rate is going to go down, but it really shows just how important it is for user-facing applications. And we achieved that without partial pre-rendering, which we'll also add soon. It was a new Next.js feature, but we still didn't upgrade to the latest version of Next.js. They seem to be coming up like every time that I open Twitter. So it'll take some time for us to upgrade to the latest version to be able to use this. But the point of the story here is that rendering shouldn't be binary. It should be strategic. You should really think about how you want to render specific content and what obstacles will that create for rendering other pieces of content on the same screen or on other screens. So at this point, everything is working well and performance was just one piece of the puzzle. But underneath everything, we had one question. And that is that how do we actually make online coding education better? The goal wasn't just to add as many features as possible. It is to make learning feel like building apps. MTX gave us that foundation. Composable, reusable, and interactive. The stack that we talked about also helped with that, allowed us to scale and move fast. And it worked well. Very soon we were able to hit 100,000 users within the first month, 18,000 learning paths created, and thousands of developers learning daily. So we went through a couple of obstacles, but at the end of the day, it is a continuous process.

And we're going to keep improving it and working on new stuff. For example, the next challenge is retention. So now that we're actually getting the users to come in and try the platform, we got to make them stay. We got to provide enough value for it to make sense for them to come back. We're going to approach it from an engineering standpoint, not just as a product lead, but trying to do maybe what Duolingo does best. Points, streaks, badges. We really learned that people want to have some kind of streaks. They want to have smart nudges. So if they're inactive, we kind of send them an email and bring them back in. And we want to create some feedback loops because even those small re-engagements, when compounded, have great impact. So these are some of the next steps because learning maybe isn't like Netflix. You got to put some effort to make people want to come and watch the next lesson.

Yeah. So to conclude the talk, I want to summarize it in a couple of key takeaways. Number one is that architecture matters. So start scalable from day one. Sure, it's not going to be perfect. Some things are going to have to be tweaked, but start with something scalable in mind and they'll build on top of it. The second one is that rendering is strategic. SSR, client-side, hybrid. You really should approach it from a strategic standpoint, not just make one decision or the other. Talking about analytics, measure what matters, not everything. Because if you could collect a lot of pieces of data, you just won't be able to make sense of it all. So rather start small, create a couple of funnels and track only the key points that matter for your users and your platform. And then, sole retention as an engineering problem. Try to come up with systems within the app so that you actually make people want to come back. Our goal always was never just to teach, but to build experiences that allow people to keep building additional stuff. And if this talk helps you build something like that too, well then it was worth it. So that's it from me. Thank you.

We've got quite a few ones. I'm gonna go from the top. Yeah, sounds good. So you kind of, you learned a lot. You talked about your learning journey, how you went about learning things, and oftentimes hindsight is 20-20. So let's rewind time. If you were going to start all over again with your new knowledge, what changes would you make to the stack? To the stack. Okay, that's interesting. The stack did evolve over time. So initially we started with a basic T3 stack, but eventually I think we used Prisma. Again, nothing bad against it. But we switched over to Drizzle. It seems that more developers are now switching over to Drizzle, not a major thing. But yeah, as I said during the talk, the TRPC and the Drizzle and that type safety, so with TypeScript for sure made a big difference. So I would definitely start with those right now. That makes sense.

And something which in the next question, we kind of talk about is developers, we go onto these websites, a lot of us, we're very privacy aware. And we don't usually allow cookies. We use web browsers that if anything, make it harder for builders, for developers to track the metrics on the websites we build. So how are you able to track the necessary metrics? This comes from Nico JS, so thank you for the question. That's a great question. So we used Google Analytics as well. If we want to eventually pair it up with Google Ads, they just make it a necessity to do that. We also use PostHog, as I mentioned. PostHog has something called cookieless tracking, which allows you to bypass some of the cookies fully legally, of course. So I think they handle the better part of that, allow this to track properly even without modern blockers. And it's also really interesting with cookies because there's a lot of stuff that is probably not great from a privacy perspective, but just knowing how a user's using your own website, it's not a privacy invasion in a lot of ways sometimes. Yeah, the data can be randomized. You don't have to get the names or the emails, you can take just the IDs and then make sense of it later on on a global scale, as statistics, instead of just individual use cases.

And this is another good question, and it brings us back to the metrics piece, which is like, what do you have in place to ensure that users are actually learning and not just stumbling by? So we had a great talk from Matthias earlier about how they use metrics to kind of quantify human psychology. Do you have anything similar or maybe even different? Yeah, that's a great question. At this point, no. But it definitely sounds like something that would make sense to implement some kind of checks, right? The quizzes could be one point that doesn't let them proceed until they answer those questions, right? But sometimes it's hard because developers oftentimes just want to fast track to do something, so they skip things and we don't want to block them if they already know some content they've learned about before, right? Absolutely. Us developers, it's a tough crowd to build for, right? Super tough crowd. Yeah, as I speak with a lot of different dev tools that we post on the channel as well, the dev real people, marketing people, tell me that developers are the hardest crowd to market to. I like it because it gives me a job. Yeah, exactly. And same thing for us. We don't try to market the developers, we try to approach them through education. So our goal is always to provide value, to teach them something. And then we give them value, they learn about it, they're going to end up eventually using it within their tools. And that's the way to get to developers, not through paid advertising or marketing. Yeah, that makes sense. That makes sense.

And the last one. What was the most common issue for the degraded performance when you're rendering everything on the server? It's like the first easy win for people. The first easy win is don't render everything on the server, right? Initially, like especially with Next.js, server-side rendering, basically, they made it the go-to default choice. Everything was rendered on the server by default. But you have to come in and tweak some things a bit, render something on the client, maybe, especially if it's interactive because it puts a lot of load on the server, especially for heavy MDX files that we had to bring back. So it just wasn't the best choice. Again, try to be a bit strategic. Try not to necessarily render everything on the server. Well, that was a very articulate way to say it depends. If you do want to ask him more questions, he will have a space at the speakers Q&A, so definitely do that. Remember, as you leave, please put your headphones on the chair you're on. It just helps the people who are coming in after you. And we're going to have a short coffee break. We're going to have many talks for the rest of the day. So we'll see you soon. Thank you, everybody. Have a great day.