Open source has played an enormous role in getting me closer to my next opportunity or goal. It has been a bridge between the life I have and the life I'm actively working towards.
Starting Chakra UI and getting to a place where it became very popular in the React community has been a journey into the unknown. I had little experience contributing to open source when I started Chakra UI, let alone experience managing such a popular project.
I was sometimes confused about what to focus on or do. Sometimes I still am. But in having conversations with my team and getting valuable feedback from the community, I’ve gained better clarity with time.
Open source has great benefits and creates options for opportunity. It can help you get hired at your dream company, create consulting opportunities, grow your network, and change your life in meaningful ways. While these benefits are great, it's good to detach yourself from them, so they don’t drive your happiness. Starting an open source project is a generous act of courage and kindness. My goal is to provide value and be helpful to as many people as possible without harming myself or others—open source helps me achieve this.
In this Guide, I’ll share my journey into open source and the lessons I’ve learned maintaining Chakra UI. I’ll show you how to create, grow, and maintain a popular open source project—even if you don’t have much experience.
Overcoming the fear and resistance
There are negative thoughts about open source that can sometimes lead to anxiety, fear, and self-judgment. It starts with the fear of being rejected, fear of someone accusing you of not being “as good as you think you are.” You might even dread the feeling of being “dragged” on Twitter, Reddit, or Hacker News.
A renowned author and writer, Steven Pressfield, describes these thoughts as “the resistance.” The resistance is the voice in the back of our heads telling us to back off, be careful, go slow, compromise. I usually recommend embracing and dancing with this fear. Be aware that it might not work, and you’re okay with it. There’s no one solution to a problem, and you’re only looking to proffer an alternative way to solve that problem.
After publishing the first version of Chakra UI, I wrote the announcement tweet and didn’t post it until three days later because I was pretty nervous, anxious, and scared of the response I’d get. I've since realized that I had learned a lot more than I thought I did from making Chakra UI over the last 3-5 years. Today, I’m grateful it turned out to be a huge success!
Every bit of open source software is a remix
“Copy, transform, and combine” is a common methodology to create a remix in the music industry, and the same can be applied to open source. Take existing solutions, pull them apart to understand the patterns, and form a perspective that either enhances existing solutions or creates a new solution altogether.
The first version of Chakra UI was inspired by existing projects like Styled System, Theme UI, TailwindCSS, and Reach UI. We observed patterns/concepts in these libraries and came up with an idea of how we’d like Chakra UI to improve the product development experience.
Your OSS project is an extension or improvement of an existing solution. It is essential that you see your first version of the project as an idea or a “point of view” that might be wrong, and your goal is to make it less wrong over time. Through feedback from the community, working with interested collaborators, and research, you’ll shape and refine that idea over time. It removes the need to have a perfect solution from the start.
The minimum viable audience
When you release an open source project, there’s a tendency that you might want to please everyone who uses your library. You might be tempted to create abstractions so it works for everyone and reaches more people. The danger is: When you seek to please everyone, you rarely delight anyone.
Every well-designed software should have a defined API surface. The problem it solves, the assumption it makes, its benefits, and trade-offs should all be clear.
I recommend seeking out a "minimum viable audience" for your project. These are friends or colleagues who understand your domain and are optimistic, driven, and open-minded enough to embrace your ideas but unafraid to tell you the truth. People who support you and want you to succeed. Double down on the feedback you get and make sure your product delights them. There’s a big chance that many more people will appreciate it, and word will spread.
I’m thankful for my three friends—Kolawole Tioluwani, Biola Oyeniyi, and Folasade Agbaje—who shared helpful feedback and excitement about the early version of Chakra UI. It gave me the confidence I needed to release it to the world!
Release early, release often
I recommend releasing your project early because minor changes or bug fixes are easier to understand and implement at earlier stages of your software’s life. It also gives the community visibility about the growth, progress, and current status of the project.
It’s vital to automate the release and changelog process from the beginning so that publishing new versions is painless. I’ve found it helpful to ensure every pull request (PR), no matter how small, includes a description of the change. Changelogs are very useful because it helps your project’s consumers see the new features, bug fixes, or breaking changes to your projects, and understand how to migrate or use them.
When I started working on Chakra UI, I used Lerna to release new versions and manually update the changelog in a `CHANGELOG.md` file.
I’m grateful for a co-maintainer, Mark Chandler, who helped improve the automation and release process using Changesetsand GitHub Actions.
Writing documentation
Creating good documentation can be the difference between people trying your project and people ultimately ignoring it. No matter how elegant your code or project is, the code won’t speak for itself. Writing documentation is the most effective way to decouple human dependencies and scale information as the project grows.
Writing about code might be pretty challenging in the beginning, but I recommend writing the way you talk. Keep your docs as easy to understand as possible, assuming no prior knowledge, using simple sentences, formatting it for easy readings, and covering as many use-cases as possible.
If people don’t know why your project exists, they won’t use it.
If people can’t figure out how to install your code, they won’t use it.
If people can’t figure out how to use your code, they won’t use it.
For Chakra UI, we set up the documentation system from the get-go using MDX, Next.js, Vercel, and of course, Chakra UI.
Asking for help
As your open source project grows, it becomes essential to keep it stable, well-maintained, and secure. Many projects grow out of a personal side project into a popular and widely-used library or framework. With a lot of attention and usage, you’ll start to receive a never-ending number of issues and pull requests. Your responsibility starts changing from just writing code to managing features requests, bug fixes, and changes while steering the project’s direction forward.
Over time, it can become emotionally and mentally exhausting to keep up with all the moving pieces. At this point, it becomes essential to ask for help and recruit new maintainers. Be on the lookout for people who contribute consistently, whether they respond to Github issues, open PRs to fix bugs, help people in the community via Github Discussions or Discord, or improve docs.
It’s also essential to provide early and helpful feedback to contributors when they suggest an idea or bug fix. People feel safe contributing to a project when they feel like their ideas/contributions are welcomed.
Let the community help you drive and shape your project while you provide its overarching vision. This is the best way I’ve found to remain sane while maintaining a popular open source project.
Take care of yourself.
As I mentioned in my Developer Story, one of the hardest challenges in open source is prioritizing yourself above all else. Your physical, mental, and emotional health are worth more than anything you create. Here are a few things I recommend.
Don’t get so attached to your project that it affects your happiness, health, or well-being.
When I reflect on the progress we’ve made with Chakra UI, I found that the reward for open source is in the people you meet, the opportunities you get, the audience you’ve built, and your personal growth.
A sad reality that I’d love to see change over time is that you might not get much financial support or backing from users of your project. This is the missing piece in open source. I recommend setting up a way to make it easy for your community to support your work using GitHub Sponsors, OpenCollective, and Patreon to receive donations for your project.
Take breaks. It’s pretty common to sit on your desk, write code, fix bugs, release new features, and write docs all day without taking a break. Remember to not overwork yourself to avoid burnout. When you feel pretty overwhelmed or exhausted, take a break, have some high-energy fun, and treat yourself with care. Maintaining an open source project is a marathon, not a sprint.
Set boundaries and maintain a healthy work-life balance. Try not to respond to issues immediately; it gives room for others to investigate and contribute.
Make sure you get high-quality rest. A rested and clear mind will solve problems 10x faster. Take care of yourself because you’re all you’ve got!
Staying ahead
Your open source project started because you had an idea or innovation you’d like to bring to the world. It’s essential to always keep this in mind.
Open source ecosystems move at a fast pace, and it can be quite challenging to keep your project relevant. Instead of learning every new library or framework, I usually try to understand the underlying concept/patterns behind them to see how that might be useful for the next major release of my project.
When I launched Chakra UI in 2019, I realized that there were other areas I needed to look into: bundle size, TypeScript, server-side rendered apps, monorepo architecture, and package distribution. These can be overwhelming initially, but I saw them as an opportunity to learn new ideas and embraced them.
It’s okay not to know everything initially and to approach your work with a student mindset, always looking to learn what’s possible and apply it to your project.
My open source mantra(s)
I find myself constantly inspired by the Engineering rule book written by the remote.com team. Here are some of the key ideas:
Unshipped work is work not done
Undocumented work, whether internal or external, is not done
Along with those, some practices we follow in Chakra UI:
When you have an idea, write a spec or quick explanation to get early feedback
Make it work
If you really need to, make it beautiful and pleasing to use
If you really really need to, make it fast, and speed it up by iterating and innovating
I’m very grateful for the change to learn all these lessons, meet amazing people, and get opportunities all along my open source journey. Maintaining Chakra UI is one of the biggest, most impactful things I’ve done in my life, and I’m so glad I get to do it.
I’d encourage anyone looking to get into open source to take the leap of faith and get started!