React Advanced

React Advanced Conference 2022

Hung Nguyen

<p>We all used open source projects every day such as npm packages, editors, web applications, and even operating systems... Have you ever thought of building one of your own? In this talk, I will share my journey building jest-preview, from when it was just a vague idea, to currently a well-adopted library to help frontend engineers write tests faster. I will share with you how to come up with an idea for a project to work on, what is the struggles you have to overcome as an author of an open source project, how to manage time efficiently, and how you get attention from engineers around the world.</p><p> by <a href="https://www.froala.com/wysiwyg-editor?pb=1"> </a></p>

How to Build Your Own Open Source Project

Hello my friend, did you enjoy Red Advance so far? I love it! And in this talk, I wanna share with you how to build your own open source project. But first, let me ask you a question. Have you contributed to any open source projects? If yes, it's great! But if no, I hope you will after my talk. Hello, my name is Hung. I'm a creator of JestPreview, a library that gives you a visual debugging experience when testing a frontend app. I'm also a core member of BestObject.org, a website that helps you to follow the growth of JavaScript ecosystem. I'm also on Twitter, let's connect! In this talk, I wanna share with you what is JestPreview and why build it, the struggle I have to overcome when build an open source software project, what did I receive from open source, and some tips if you want to build your own. First what is JestPreview and why build it? The problem is that if you're an engineer, if you're a frontend engineer and you write tests, you have to work with node terminal a lot. If you encounter a bug, you have to look at the long HTML in the terminal, and it's very hard for you to debug and fix it. You don't even know what your app looks like when your test is running. Have you ever tried to click a button, but actually there's no button, it's just a spinner loading in your test? So I asked myself a question, if Jest can print out the HTML, can we render it on a real browser? And until now, the answer is yes we can. As you can see, this is a test case written in React Testing Library, the user interaction is controlled by UserEvent, and instead of using screen.debug, we use preview.debug to see the actual UI on our app in the browser, and whenever you hit save, the browser updates the new UI almost immediately. It brings a lot of benefits. First one is you can debug a failed test much much easier. You can know what your app looks like, so you can very easily write your next testing step so you can write your test faster. And even though you are writing unit or integration test, you can still see the UI, so it tries to close the gap between unit test and integration test with end-to-end test. And in my personal experience, I write test 2-3 times faster thanks to Jest preview. I wanna show you some demo. As you can see, this is a normal app that written in React Testing Library. In the right side, you can see that this is the UI Jest preview shows you. Let me just comment one step, and the test will rerun again, and you can see the count number decrease from 6 to 5. Let me just decrease it again. You can see it's from 5, it's gonna turn to 4. And that's Jest preview. And now I want to share some struggle I have to overcome when building an open source software project. First, it's difficult because when you use a framework, you do not need to understand it deeply. But when you build an open source software project, it's likely that you need to understand it very detailed. Sometimes you want to ask a question, but it's likely that you cannot find an answer on Google or Stack Overflow. For example, this is how CDS module works. But when I build Jest preview to support CDS module, I have to dig into the source code of CDS module. And this is the code I have to work with to make Jest preview work with CDS module. But it's a good chance for us to learn because whenever we overcome a hard problem, we learn a lot. Next is time, open source software takes a lot of time, especially if you have a full-time job. So you have to manage your time well. And my advice is always have a plan. And this is my favorite quote, is a good plan today is better than a perfect plan tomorrow. Next, I used to think that since it's an open source project, many people will come to help you. But actually not true. For a small open source project, you might be the only maintainer. Sometimes you just want to keep up or archive the project. But that time, please remember why you start it in the first place. And next is financially. If you just do it for fun, it's okay. But if you are serious about working on open source, yeah, you may consider GitHub sponsors, Open Collective, or even some premium model. And I want to share what I received from doing open source. First is knowledge, a lot of knowledge. I know how Bundler works under the hood. I know how to process CSS in modern web applications. And I have to read open source code a lot. So my code reading and developing skills improve. I understand how the tool works under the hood. It makes me a better programmer. Next is the opportunity. I received a lot of opportunity from doing open source. My project just got nominated for the most exciting use of technology, React Open Source Award in React Summit. It's just very exciting. And I haven't ever thought of that before. For job, I received a lot of invitation to apply, and it's just crazy, because you do not need to find a job, but it will find you. And next is a conference and tech event. I have a chance to join that. Next is I have a chance to chat with many great engineers, authors of open source software, libraries that I use every day. Before doing open source, I have never thought that I can discuss technical with them. But great that I met some of them in person. You might recognize some of them here. And next is that I receive a lot of thanks randomly in a day that I receive something like thank you for making this. It makes my life so much easier. And that really motivates me to keep doing it. I never experienced that before when I'm just doing a 9-to-5 job. So how to do that? Now I want to share some tips to build your own open source project. First is how to choose an open source project to work on. The answer is very easy. It should be the project you use every day. If you want to build your own open source project, your future project should solve your own problem. It's very difficult to contribute to a project that you don't have a context. Just pick one project that you use every day and contribute to it. And you know that in a daily job, we spend a lot of time on a particular problem. And there's a high chance that other people have the same problem. So just open source it. And it does not need to be something very big. Next start simple. No projects are complicated when it's work-related. Just start simple. Just make a MVP or proof of concept first. And improve it over time. And it's okay if the code is not clean in the starting phase. And if you ever get lost, it's okay. That's a sign that you're going to learn a lot. Next is a file maintainer. You know, building an open source project is hard and stressful. So it would be so much easier for you to have someone to discuss technical and motivate you to continue the project. And do not start at version 1. Because a new project is full of proof of concept and experiments. Version 1, that means your software must be backward compatible when you release a new version. And in semantic version, the term is major version ratio 0. It's for initial development. Everything may change and anything. And the public API should not be considered stable. There, you can move fast. Next is when you start a project to solve a particular issue. But when you use it as a normal user, you know if it's good enough. If you need to adjust it or add more features to make it more usable. For example, when I build Jest preview, all I want is to preview the UI in Jest to Chrome, period. But the more I use it, the more features I add to make it easier to use. Like auto reload on save, proceed CSS, an image, and adding a new automatic mode, etc. Next, you have a project but it can be subjective. Let's ask your friends, your colleagues, and your network that what project should change to be more usable. After a while, when your project gets more attention, watch out for the issue and discussion tab. And you know your software is being used when people start to report issues and send pull requests. I see it like magic how you just put something on GitHub and people from around the world come to you and find issues or send pull requests. And it's very important to guide people how to categorize and find issues efficiently. And reproduction is the most important one. Because without reproduction, it's very difficult for maintainer to fix a bug. And there are many other features from GitHub to make you work with open source so much easier like labels, milestones, and GitHub actions. And next advice is let's learn from others. There are famous quotes like good artist copy great artist steal. So do not reinvent the wheel. There are much good software out there and that already solves your problem. Learn from them. Read their source code to see how they do. Let's preview learn from many amazing projects like Vite and CreateRake app. Next you should write documentation. It's very easy for you to use your own software but people around the world have different and special use case. So that's why what problem your project trying to solve. Documentation uses and some caveats they might encounter clearly in the document. If you prefer React, you can use DocuSource. If you prefer Vue, you can use VitePress. Both of them help you to make documentation effortlessly. And next share it with the world. Share it on Twitter. Add some blog posts and share your project in a tech event. And last but not least, contribute to open source today. I hope you will have a lot of fun and learn a ton doing open source software. So thanks for your attention. If you write, find and test, try just preview. And if you like it, please give it a star to support me. And the slides are available and open source at redadvance.hung.dev. Thank you.
