Scaling a React Application from 0 to a Brazilian Users

A real-world lesson from scaling a JavaScript application. So around three years ago, I was in a very difficult position. I was nervous. I couldn't focus on anything. I was staring at my phone every two minutes because I had a really big decision to make. I decided to change my job, and I had two big offers on the table. I could either select a high-paying senior software engineer at a public company which had over a thousand engineers, or I can choose a tech co-founder position with little to no pay but with equity in the company and the opportunity to build the software from scratch.

And I realized that I love building things and getting my hands dirty, and this is a really big but, I always leave projects with just the windows and doors that are missing, like in the small video here. So I decided that this was the perfect opportunity to experience building something from zero. But what did I agree to? What was the idea that made me turn down a lucrative salary and the comfort of a nice stable job? And the basic premise was this.

We're going to war with the apply to job button. This product is for universities only, so I'm not trying to sell you anything. But we don't say, don't bother. We say, don't bother applying to jobs, network and build lasting relationships so you can get recommended for open positions. And there are all sorts of companies that do this. And the original founders, Max and Marcus, were students themselves, and they wanted to build something for students by students. So they met up one night over a couple of beers and drew up the career OS, that's the company name, flow on a piece of paper. And it looks something like this.

They collected the emails of around 30 decision makers from schools with buying power and send them cold emails. Now, this is an example of an email that they sent two years ago. So I want to stress out that at this point there was no startup. There was no money. There was no product. They just wanted to validate their idea. If nobody answered their cold email, the idea was a bust. Instead, even though it was Christmas holidays, they got around 10 responses back. Then and only then they decided, OK, the idea was worth pursuing and they went full steam ahead with finding a technical co-founder, myself, and raising money to build a startup.

Now, the biggest mistake I noticed tech entrepreneurs make is this. They get an idea for a business. Now, I think this has happened to every one of us. So if you have an idea, you'd probably do this. You start building your MVP and implementing an MVP. And then for those who build an MVP, they go ahead and validate it with the wrong people. Usually they ask their friends, they ask their work colleagues or even their parents. And then with their MVP and their mother's blessing, they try to raise money.

Now, these pillars have to go hand in hand from start to finish, like we did with CareerOS. We validated the idea without any money spent just by sending emails. Then when we got the response, we sent emails to investors who usually invest in higher ed tech industry. And we didn't try to get money. We didn't have anything transactional proposed. We just gauged their interest. We just asked them for feedback. And just to let you know, investors love to give feedback. So every month we kept potential investors and clients informed about our work and we kept potential hires in the pipeline. Now, in this email, we were mentioning that we send this to all sorts of people like friends, family, mentors. We were actually sending it to potential investors or potential clients.

In this email, we mentioned sending it to various people like friends, family, mentors, potential investors, or clients. Our communication channel served as the primary acquisition channel. After six weeks, we had our first MVP, focusing on building relationships for dream companies. With this MVP, we gained four paying customers and secured $800,000 in our precinct round to hire a team.

Thirteen years ago, at my first job as a programmer, I faced various technologies like Angular 1, Angular 2, React, V2, Nuxt2, Laravel, and PHP. Time is a critical enemy when choosing a framework due to the rapid changes in the industry. Upgrading or changing the tech stack was crucial to avoid being left behind or hindered by outdated technology.

Learning from NASA's modular design approach for the International Space Station, I implemented a similar strategy for my app. Each module had specific guidelines, structure, and interface, emphasizing a design system and component library. To prevent UI errors from the past, the focus was on reusability, avoiding UI libraries, third-party tools, and no-code solutions.

I had to work with React when it had class components. In another company, I was using V2 and Nuxt2. Sometimes I did Laravel or PHP. So I can tell you that when building a product and choosing a framework, your biggest enemy is time. In our industry and ecosystem, every week something new appears and you don't want to be left behind, or worse, being incapable of developing something because your stack is outdated.

Think about trying to integrate OpenAI SDK inside Angular 1. It's practically impossible. We're trying to hire new Angular 1 developers in 2025. I'm sure you can find people who are capable of coding in Angular 1, but do they want to do it? I don't think so. So in choosing the tech stack for our company, my biggest fear was being left behind. So I made some rules to make sure we can always upgrade our stack or change it completely. So I didn't want to use any UI library. We want to build our own component library. I didn't want to use any third-party libraries, and I didn't want to use any no-code tools.

So the ISS was built using modular design, and they just shipped, during 30 years, different parts of the space station. So when designing my app, I wanted to work the same way. Each module had dedicated guidelines, folder structure, and interface. But for them to work, we also needed a design system and component library. I didn't want to repeat the UI mistakes of my past, and I wanted to make everything reusable. So the first file I created in the app was actually CSS variables, SAS typography, mixins, to ensure we always follow the same design patterns. And of course, each component had to have a unit test, a storybook, and accessibility tests.

And of course, each component had to have a unit test, a storybook, and accessibility tests. Now, I had so many rules in place when I started, I forgot this famous quote by Mike Tyson, like, everyone has a plan until they get punched in the mouth. So the first punch was more of a slap, but we realized that no third-party app rule was practically impossible. It happened first with the drag-and-drop feature of Arcamba. No matter how much I tried, I just couldn't get it to be perfect. And after two or three days of frustrating coding, I gave up and installed React Beautiful DND.

Then we had to install Firebase for other projects, then analytics. Then we needed to handle rich text, so we added React Quill. Different analytics like June, Google Analytics, Customer IO, Sentry, React Loading for videos, React PDF when we built the resume builder. And as you can see, it snowballed out of hand. Can't even fit it in the image. We have more than 60 third-party libraries currently in the app. And in each library we added, our ability to migrate and keep the app up to date decreased, which is something I really dreaded.

So what did we do? Well, for each third-party tool we added, we created a wrapper component or proxy that exposed an interface that we used in different parts of the app. This way, if we ever needed to replace Mixpanel with something else, we just had to change it in this wrapper component and make the new library use the same interface as the old one. We went a step further. Instead of calling different events in our product, we encapsulated all our analytics in an analytics module. This way, if we ever need to add another tracking library for, let's say, Algolia events, we just add them here in the user analytics hook and they're automatically applied everywhere in the app.

And it also made it super, super easy to remove modules as well. Now, all our third-party libraries, around 60, are encapsulated in their own wrapper module. And this also helps with the build process because if you import a third library from Node modules all over your app, it might increase the chances of being added twice inside of the build.

Now, another punch we received was with our component library and design system. A year in our start of life, we started our third project. And then we decided, okay, initially we had all our components in the same root folder. And then we decided, okay, let's move it to an npm package. We thought it was going to be easy, but we were dead wrong. We had around 50 components at this time. And we decided to just start small and started with the button. But after moving everything and having the button component work for our component library, we thought, okay, now the hard part is over.

There are 49 more components to go. It's an easy adventure, 20 minutes. Let's go. Reality was another punch. We thought we kept all our components dumb, but unfortunately, a lot of project-related logic crept inside of the components, like router-based navigation, state-related values or even API calls in some extreme cases. And we also had a race condition. By the time we moved the component inside a component library, in the folder, it might have already changed in the main project. So the team velocity was so fast that our technical depth was hitting us hard.

So we tackled this in three stages. Figma as a source of truth, move components one by one and assign a project lead who was in charge of distributing work, but also mandatory reviewer to not allow the component folder inside of the project to be worked on anymore. And then move storybook CICD and create a CICD pipeline that keeps the main app and library in sync. So if there's one thing I would change, if I can go back in time, I would do the npm package from the start and not wait until it's needed.

Another punch I received was a serious implementation mistake we did. We started noticing a year into our startup that DevTools in the browser was starting to get slower and slower. Eventually, it became unusable. Now, the reason for this was we noticed that the styles were being loaded a thousand times for each component from models that we're using. So everything was fine in the final build because it had tree shaking, but in the dev mode, it was not working. Now, I assume the issue was with importing SAS as additional data inside of our Vite config.

And at first, I thought it was because we were using the import keyword and not the use keyword. So I changed that. This made it better and cleaner. And now I could observe what files were being imported over and over again. So then I noticed that it was just our CSS root rules, like our variables. And looking in the files, I realized that I put these in the typography inside of the utility, which are SAS files. So I also added there the CSS files.

So if you don't know, when you use additional data, you only need to have SAS related data inside of additional data. So, for example, in variable CSS, it should be only SAS variables, SAS functions, and SAS mixins. And me, because I added CSS, it added for every component the CSS at the top of the component. So I went to work. I moved all root files in a global CSS file that I imported in index.html. And the problem went away. And to make matters even more embarrassing, this one fix saved us like 200K of our final JavaScript build.

Now, about bundle size, we kept adding features. So our bundle kept increasing and performance was degrading. So we decided to use the lazy of our main roots using React.lazy, like this. So what happens when you do this is if you go to a page, it will load that page-related code only when you click on the navigation. But the problem was that as soon as we did this, in production we started getting some errors, which is failed to import dynamic module error. Now, this was happening because every time we deployed, if there are people using the app and they click on the navigation, our deploy process deletes the old hash that the deploy is using for cache-busting purposes and updates it with a new one.

Now, Vite has a pre-load error event that you can listen to globally. And when this happens, it simply reloads the page and this worked 99% of the time. But for a pesky 1%, they were using old browsers or mobile Safari for some reason, it stuck them in an infinite loop. So we explored different solutions. And of course, the safest one was to not delete the old hash from the disk and keep one or two versions in prone so this doesn't happen. And this, again, worked for 99% of the time, but when we had API breaking changes, it made also the app crash, which we also didn't want. And eventually, we landed on our final solution where we kept both versions of the hash, but instead of being a random hash that Vite generates, we used our app's package version as the version number, as the hash. And then when we do a deploy, we have a service worker that actually runs in the background, checks for a new API version, and every time there's a new API version, it updates the source maps of the user's internal manifest.

And then when we do a deploy, we have a service worker that actually runs in the background, checks for a new API version, and every time there's a new API version, it updates the source maps of the user's internal manifest. So all in all, it's been over two years. We are using the latest React, the latest Vite, and the latest TanSec. And we're pretty happy that we kept technical depth as close to zero as possible while moving very, very fast in building a consumer-facing product. Our app is very good now, if I'm being honest, but one year ago, we were flooded with bugs, either functional or visual. Our app was breaking every day, especially during sales calls. We were holding our breath for it not to break, and sadly, it usually did. It got so bad that everyone had a running joke that our app was only working for 60% of the time.

So what did we do? Well, we first implemented a no-broken-windows policy. So if you don't know, the broken window theory states that if a neighborhood has a broken window, it normalizes crime and raises crime rates. And it happens in apps as well. If you already have bugs in the app, you just pile them in the backlog, creating a normality of the app having bugs and breaking. We said enough is enough. And every Wednesday for the whole summer, we dedicated six hours a day to bug squashing, a competition where we took all bugs from the backlog and fixed them, from functionality bugs to visual bugs to even small improvements and animation delights.

Now, being the summer with the Olympics, we made it a competition with medals and awarded Amazon gift cards to the winners. It actually took me two weeks to find the solution where I am first. So it was a huge success to cleaning up our app. And as you can see, but that was just half the battle. We wanted to make sure that the functionalities don't creep up in our products. So we implemented a different way of working. Our front-end app was hosted on Netlify. And Netlify has the ability to create deploy previews. And, of course, you can... Vercel has the same and other hosting providers do the same. But we use these previews to do design acceptance, QA testing and product acceptance before anything is actually merged into main. Then we created a pretty sweet release process where every time you merge something, we have a GitHub actions that takes the PR title, determines the semantic version, if it's major, minor or breaking change. And then it adds this to our draft release on GitHub.

So on the left, you can see everything that's not being released because we don't have CI CD. We manually push a button. So if you want to read more about this release process, I have a complete tutorial on my blog, nechudan.dev.

But finally, we made some strong recommendation on every theme to use Coursor. And that way, we created Coursor rules that contain how to write our SAS, how to write our HTML, using BEM syntax for classes, how to write our types, react, our test. Now this made it easier for back-end developers to enter the code base and use Coursor and make changes if they need it. And for new joiners to be on-boarded faster.

Then in the PR itself, everyone has to put in what has changed and add to videos with before and after to make it easier for testing and product acceptance. Now fast-forward in just two years, we sold our product to over 50 universities worldwide, including big names like Oxford, Berkley, Stanford. And with best practices in place, we built this product in just two years.