Forem: John

How to Build a Public Open-Source Project People Actually Want to Clone, Use, and Contribute To

John — Mon, 13 Apr 2026 12:42:18 +0000

Most public repositories do not fail because the code is bad.

They fail because:

nobody understands why the project exists,
it is hard to run locally,
the repository looks like an abandoned side experiment,
and there is no clear reason for anyone to come back a second time.

If you want to build public open-source projects that attract attention on GitHub, earn stars, and gain real users, you have to think about your repository as more than a folder of code.

You have to treat it like a public product.

In this article, I’ll show you how to build modern open-source projects so they:

look credible from the first visit,
are easy to run,
invite contributions,
and have a much better chance of growing organically.

1. Start with a problem, not with a stack

A very common mistake looks like this:

“I’m going to build a new project in Next.js / FastAPI / Rust / Bun to practice.”

That may be a fine learning project, but it rarely turns into a strong public project.

Repositories that have the best chance of getting traction usually solve one clear problem:

they save time,
simplify something,
automate something repetitive,
or show a modern, opinionated way to build something useful.

Better ideas than “another starter”:

a starter with a real-world use case,
a boilerplate for a specific product type,
a tool that solves a small but frequent developer pain point,
a team-ready repository template,
a dashboard, generator, CLI, integration, or mini-SaaS released as open source.

A good rule of thumb:

If you can’t describe the project in one sentence without naming technologies, the idea is probably still too vague.

Instead of:

“This is a project built with React, Node, Prisma, and Docker.”

Say:

“This is an open-source starter for building admin panels with authentication, roles, billing, and deployment already set up.”

People click on problems.

Not on stacks.

2. Build a small but complete vertical slice

A public project does not need to be huge.

It needs to feel complete.

That is a big difference.

It is far better to show:

working authentication,
one clean core workflow,
solid UI,
sensible folder structure,
documentation,
and a simple deployment path,

than to show 27 half-finished features.

The most shareable open-source projects are often the ones that create this feeling quickly:

“Okay, this works. I can see how I would use this.”

That’s why modern public apps should include:

clear onboarding,
a demo or screenshots,
fast local setup,
sample data,
a useful .env.example,
and one obvious way to run the project.

If someone needs 40 minutes just to reach the first useful screen, you lose most potential users.

3. Treat your README like a landing page

In practice, your README is your project’s homepage.

That is where visitors decide, often within seconds:

whether to stay or leave,
whether to star the repo,
whether to clone it,
or whether to close the tab.

A good README does not begin with:

“Project X is a modern application that aims to…”

It begins with a clear value proposition.

What your README should include near the top

1. A one-line pitch

Make it obvious:

what it is,
who it is for,
and why it matters.

Example:

An open-source SaaS starter for building modern web apps with auth, billing, roles, and deployment built in.

2. A screenshot, GIF, or live demo

People understand software much faster when they can see it.

If it’s an application, show:

the dashboard,
onboarding,
settings,
or the core workflow.

3. A “why this exists” section

Briefly explain:

what problem you are solving,
how the project is different,
when someone should use it.

4. A fast start section

Keep it short and practical:

clone,
install,
env,
run.

5. Key features

Not every feature.

Only the ones that actually communicate the value.

6. A roadmap

People are more likely to follow a project when they can see where it is going.

7. A contributor section

Even a short one helps.

It should be obvious how someone can get involved.

A README does not need to be long.

It needs to be clear, concrete, and easy to scan.

4. A public repository has to inspire trust

A lot of repositories look promising at first glance.

Then you open them and discover:

no license,
no idea whether the code can be used,
no contribution rules,
no issue templates,
no signal that the project is actively maintained.

If you want people to take your project seriously, you need the trust layer of open source.

At minimum, have:

README.md
LICENSE
CONTRIBUTING.md
CODE_OF_CONDUCT.md
SECURITY.md
issue and pull request templates
a meaningful repository description

These are the details that separate:

“I uploaded some code” from
“I’m building a project people can join.”

5. Optimize the first five minutes

The most important moment is not when someone stars your repo.

The most important moment is when someone tries to run it locally.

If they hit:

missing environment variables,
outdated setup instructions,
confusing scripts,
broken migrations,
or secrets hidden in config files,

they are usually gone.

That’s why you should test your project as if you were a stranger discovering it for the first time.

My simple pre-release checklist

Before making a repo public, I ask:

Can a new person run this without asking me questions?
Does the README answer the most obvious setup questions?
Is the configuration predictable?
Are the error messages understandable?
Do sample data or seed scripts help show value quickly?
Are the script names obvious?
Can this project run on a clean machine without guesswork?

This usually matters more than one more feature.

6. Package the repository like a product

Strong public projects are not only well-built.

They are also well-packaged.

If you want more visibility:

choose a clear repository name,
write a sharp description,
use relevant tags/topics,
add a social preview image,
publish real releases,
show progress through changelogs and updates.

This is especially important for:

modern web apps,
starters,
boilerplates,
developer tools,
templates,
and infrastructure projects.

People often judge project quality from the repository page itself:

is the name clear,
is the description useful,
is the value obvious,
does the project look active?

Your code can be excellent and still get ignored if the repository looks neglected.

7. Build community around the problem, not just the code

A lot of people think open source is only about pull requests.

That is too narrow.

People can add value in many ways:

reporting bugs,
suggesting features,
improving documentation,
testing edge cases,
sharing feedback,
explaining how they use the project.

That is why you should create a space not only for code changes, but for discussion and learning.

Helpful tools include:

issue templates,
labels like good first issue,
help wanted,
a public roadmap,
a list of contribution ideas,
an FAQ,
discussion threads,
or a feedback board.

The less friction people feel, the more likely they are to participate.

8. Publish early, but do not publish chaos

“Ship early” is good advice.

But “make it public early” does not mean:

“Throw everything online before it makes sense.”

Before you promote a project, make sure it is at least:

understandable,
runnable,
documented,
and safe to share publicly.

This matters even more if you are building in public on:

X,
LinkedIn,
DEV,
Reddit,
Hacker News,
newsletters,
or YouTube.

One of the most common mistakes in open source is promoting a project too early:

before the README is useful,
before setup works,
before the value proposition is clear.

The result?

Traffic arrives, but it does not turn into:

stars,
watchers,
issues,
contributors,
or real users.

It is better to publish a week later and make a strong first impression.

9. Think repo-first for modern apps

If you are building a modern app in public, your repository is part of the product.

It does not just store code. It:

sells the idea,
documents decisions,
builds trust,
shows quality,
and invites people in.

A modern repository should answer these questions immediately:

What does this do?
Why does it exist?
How do I run it?
How do I use it?
How do I report a problem?
How do I contribute?
What direction is the project going?

If those answers are visible from the beginning, your repository starts working for you even when you are offline.

10. A simple checklist before publishing on GitHub

Use this as a lightweight definition of done for any public project.

Product

[ ] The project solves a specific problem
[ ] There is a clear use case to show
[ ] The value can be explained in one or two sentences

Repository

[ ] The README is clear and concrete
[ ] There is a screenshot, GIF, or demo
[ ] There is a LICENSE
[ ] There is a CONTRIBUTING.md
[ ] There is a CODE_OF_CONDUCT.md
[ ] There is a SECURITY.md
[ ] Issue and PR templates are ready

Developer Experience

[ ] There is an .env.example
[ ] Setup works from zero
[ ] Commands are simple and predictable
[ ] There is seed or sample data
[ ] The project runs without guesswork

Visibility

[ ] The repo has a good description
[ ] The repository name is easy to understand
[ ] Relevant tags/topics are added
[ ] A first release is prepared
[ ] The next steps are visible

Final thought

Open source does not win on code quality alone.

It wins through a combination of:

usefulness,
clarity,
trust,
easy onboarding,
and consistent visible progress.

If you want to build public projects that actually grow, do not just ask:

“How do I write better code?”

Also ask:

“Will a random developer on the internet understand this project, run it, and want to come back?”

Because that is where real public open source begins.

If you are building public repositories yourself, I’d love to know:

What kills open-source projects fastest in your experience — scope creep, weak onboarding, poor README, inconsistent updates, or something else?

Working on Cabal v3: reviving a P2P mobile chat app with React Native

John — Mon, 13 Apr 2026 08:33:42 +0000

Right now I’m working on Cabal v3 — a modern peer-to-peer chat app for Android built on top of the Cable protocol.

This project is both a modernization and a revival of the older cabal-mobile effort:
https://github.com/cabal-club/cabal-mobile

The original project was created to let people chat with the P2P swarm on mobile devices, and its last tagged release (1.0) goes back to June 17, 2018. Later, the project README pointed development toward a v2 branch, so the idea of evolving the mobile client has already been part of its history. 1 2 3

What makes this especially interesting to me is the protocol underneath it.

Cable is a lightweight protocol for peer-to-peer private group chats, where peers communicate directly instead of depending on a centralized server. The protocol is designed around encrypted communication between equal peers and the exchange of cryptographically signed chat data. 4 5

For me, this is not just an interesting open-source revival.

It’s also a really good opportunity to learn more about building a mobile frontend with React Native while working on something rooted in decentralized communication.

So this project sits at a really interesting intersection for me:

mobile development
React Native
Android
open source
and peer-to-peer systems

Still early, but I’m excited to keep pushing it forward.

From NASA Exoplanet Query to ExoVault: Building a Better Data Exploration Experience

John — Sat, 11 Apr 2026 13:25:13 +0000

Other project idea I recently decided to build in public was inspired by the NASA Exoplanet Query prompt from the App Ideas repository.

That project eventually became ExoVault:
https://github.com/johnnylemonny/ExoVault

What started as a structured data query idea turned into something much more interesting for me:
a more polished, cinematic interface for exploring NASA exoplanet archive data.

The original prompt

The NASA Exoplanet Query idea is already a really good challenge.

It’s built around:

working with NASA archive data,
loading CSV efficiently,
minimizing delays at startup,
and building a query interface that lets users filter exoplanet data by fields like discovery year, method, host name, and facility.

That made it appealing right away.

It wasn’t just about rendering data.
It was about thinking carefully about:

ingestion,
structure,
search,
and presentation.

What pulled me into this idea

What interested me most wasn’t only the dataset.

It was the possibility of taking something that could have been “just a query tool” and pushing it toward a better exploration experience.

I kept thinking:

What if this felt less like a utility screen and more like a discovery product?

That question shaped the direction of the whole project.

Instead of building only the minimum query UI, I wanted to create something that felt more deliberate, more visually refined, and more enjoyable to explore.

That’s where ExoVault came from.

How ExoVault evolved

In my version, the project became a more premium archive explorer built around:

a custom CSV-to-JSON data pipeline,
a high-performance frontend,
compare mode for exoplanetary systems,
glassmorphic visuals,
and a more cinematic browsing experience.

I built ExoVault with:

Astro
React
Tailwind CSS
TypeScript

and used a custom data pipeline to process NASA’s raw CSV into optimized JSON payloads.

That part was especially satisfying because it made the project feel more complete end-to-end:
not just UI, not just data handling, but both working together.

What I wanted the project to feel like

One of my goals with ExoVault was to make exploration feel intentional.

Not just:

filter,
search,
render rows,
done.

I wanted the archive to feel like something people would actually want to browse.

That meant paying attention to things like:

visual hierarchy,
transitions,
compare flow,
and how the interface frames the data.

I think there’s a big difference between “showing information” and “creating a discovery experience.”

This project made me think a lot about that difference.

What I learned while building it

A few things stood out while working on ExoVault:

1. Data projects become more interesting when presentation is treated seriously

A structured dataset can feel dry or compelling depending on how the experience is shaped.

2. Prompt-based ideas are often stronger than they first appear

The original App Ideas brief gave me a very solid technical core.
The interesting part came from deciding how to evolve it.

3. Frontend polish matters even in data-heavy apps

If the interface feels flat, the whole experience feels flatter too.
Good data presentation is also a UX problem.

4. Public repos push me toward stronger execution

Knowing the project would live openly on GitHub made me care more about the quality of the pipeline, repo structure, documentation, and overall presentation.

Why I like using structured prompts as a starting point

I think structured prompt repositories are one of the best ways to build momentum — especially if you don’t treat them as the finish line.

That’s how I’m trying to use them.

Not as instructions to copy,
but as a framework to build from.

The prompt gives me:

direction,
constraints,
and technical focus.

Then the real project begins when I start asking:

how should this feel?
what should be improved?
what makes this worth sharing publicly?
how can this become more than the base brief?

ExoVault is probably one of my clearest examples of that so far.

From a Calorie Counter Prompt to a Local-First Nutrition Tracker

John — Sat, 11 Apr 2026 13:06:38 +0000

One of the things I’ve been trying to do lately is take project prompts seriously enough to turn them into public, polished repositories instead of leaving them as half-finished exercises.

That’s exactly what happened with NutraFlux:
https://github.com/johnnylemonny/NutraFlux

The project was inspired by the Calorie Counter idea from the App Ideas repository, but I didn’t want to stop at “search foods and show calories.”

I wanted to push it into something that felt faster, cleaner, and more product-like.

The original idea

The original Calorie Counter prompt is already a strong one.

It focuses on:

searching foods,
showing matching results,
calorie values,
and working with structured nutritional data.

It also introduces useful technical constraints:

transforming raw food data into a format that is easier to search,
limiting results,
and thinking about performance and search strategy.

That made it a really good foundation.

What interested me most

What grabbed my attention wasn’t just the calorie tracking part.

It was the opportunity to build a nutrition tool that felt:

immediate,
search-first,
and frictionless.

A lot of apps in this space feel slower or heavier than they need to.

So instead of treating this as a basic exercise, I started asking:

What would this feel like if I designed it more like a fast, privacy-friendly product?

That question eventually led to NutraFlux.

How NutraFlux evolved

In my version, the idea became a local-first daily calorie and macro tracker built around speed, privacy, and a more refined frontend experience.

NutraFlux includes:

instant search-first logging,
wildcard food lookup,
meal categories,
calorie budgeting and progress indicators,
favorites and recently used foods,
adaptive design,
and a more polished visual system.

What I liked most about building it was that the original prompt gave me a functional core — but the product identity came from the decisions I made around it.

That’s where it stopped feeling like a challenge and started feeling like my own project.

Why I made it local-first

One of the biggest choices behind NutraFlux was making it strictly local-first.

Everything lives in the browser:

nutritional data,
settings,
and food history.

No account wall.
No cloud sync.
No user data leaving the device.

I really liked that direction because it made the product feel:

faster,
more private,
and more focused.

It also changed how I thought about UX.

When everything happens instantly and locally, the interface itself has to carry more of the experience.

That made clarity, speed, and smooth interaction much more important.

What I learned from building it

A few things really stood out while working on this project:

1. A strong prompt is a good starting point — not a limitation

The base idea gave me a clear direction, but the interesting part was deciding how far to take it beyond the original brief.

2. Product feel matters as much as base functionality

The app can technically work, but it still won’t feel complete unless the UI, feedback, and flow are treated with care.

3. Privacy can be part of the product identity

Making NutraFlux local-first wasn’t just a technical detail.

It became one of the reasons the app feels different.

4. Public repos raise the bar in a good way

Once I knew this would live publicly on GitHub, I thought more carefully about polish, structure, and presentation.

Why I like building from prompts this way

I think project prompt repositories get underestimated sometimes.

But for me, they’re useful because they remove just enough uncertainty to let me focus on what really matters:

interpretation,
technical decisions,
UX,
polish,
and project identity.

NutraFlux is a good example of that.

It started as inspiration from a calorie counter prompt.
Now it’s part of the kind of public open-source work I want to keep building more of.

I Built a Free Hydration Tracker with No Signup: Here’s What I Learned

John — Fri, 10 Apr 2026 16:56:20 +0000

I recently built Drink Daily, a hydration tracking web app designed to be free, simple to use, and available without registration.

🔗 Live app: https://drink-daily.vercel.app/en

This is one of the projects I’m most proud of so far, not just because it works, but because it reflects the kind of products I like building: practical, lightweight, and polished enough to feel good to use.

Why I built it

A lot of small health-related apps create friction too early.

You open the app and immediately hit:

a sign-up wall,
limited functionality,
too much clutter,
or an interface that feels more like a form than a product.

I wanted to build something different:

useful from the first visit
no registration required
clear and focused
pleasant to interact with
good enough to feel like a real product, not just a demo

Hydration tracking felt like a good fit for that kind of experience.

What Drink Daily is

Drink Daily is a free hydration tracking app that helps users keep track of daily water intake without forcing account creation.

The goal was to keep the experience:

frictionless,
fast,
understandable,
and easy to return to.

Instead of overcomplicating the idea, I focused on making the core experience feel smooth and intentional.

What I wanted to get right

When I started building it, I cared about more than “just making it work.”

I wanted the app to feel:

1. Simple

The app should be easy to understand immediately.

2. Lightweight

No unnecessary barriers, no bloated flows, no forced registration.

3. Polished

I enjoy building interfaces that feel refined, so I paid attention to layout, spacing, clarity, and the overall experience.

4. Actually usable

Even for a small app, I wanted it to feel like something people could genuinely use — not just click through once.

What I learned while building it

Building Drink Daily taught me a lot about the difference between having features and creating a good experience.

A few things stood out:

Product decisions matter as much as technical ones

It’s easy to keep adding features, but choosing what not to add is just as important.

Small UX details make a huge difference

Spacing, hierarchy, naming, and flow can completely change how “finished” a project feels.

Friction shows up fast in simple apps

When the app itself is simple, every unnecessary step becomes more noticeable.

Public projects feel different

Building something you’re willing to show publicly makes you think more carefully about quality, clarity, and polish.

What I’d improve next

Like most projects, this one still has room to grow.

Some things I’d like to improve or expand over time:

deeper progress insights
more personalized tracking options
more refinement in the user flow
additional quality-of-life improvements
continued UI/UX polishing

I also want to keep improving how I present and document my public work.

Why I’m sharing it

I’m currently growing my public developer profile and becoming more active in open source and build-in-public style sharing.

This project felt like a good first thing to share because it reflects what I enjoy most:
building practical web apps with a strong focus on clean UI, smooth UX, and modern frontend development.

If you try the app, I’d genuinely appreciate any feedback:

What feels good?
What feels unclear?
What would you improve?

Forem: John

How to Build a Public Open-Source Project People Actually Want to Clone, Use, and Contribute To

1. Start with a problem, not with a stack

2. Build a small but complete vertical slice

3. Treat your README like a landing page

What your README should include near the top

1. A one-line pitch

2. A screenshot, GIF, or live demo

3. A “why this exists” section

4. A fast start section

5. Key features

6. A roadmap

7. A contributor section

4. A public repository has to inspire trust

5. Optimize the first five minutes

My simple pre-release checklist

6. Package the repository like a product

7. Build community around the problem, not just the code

8. Publish early, but do not publish chaos

9. Think repo-first for modern apps

10. A simple checklist before publishing on GitHub

Product

Repository

Developer Experience

Visibility

Final thought

Working on Cabal v3: reviving a P2P mobile chat app with React Native

From NASA Exoplanet Query to ExoVault: Building a Better Data Exploration Experience

The original prompt

What pulled me into this idea

How ExoVault evolved

What I wanted the project to feel like

What I learned while building it

1. Data projects become more interesting when presentation is treated seriously

2. Prompt-based ideas are often stronger than they first appear

3. Frontend polish matters even in data-heavy apps

4. Public repos push me toward stronger execution

Why I like using structured prompts as a starting point

Links

From a Calorie Counter Prompt to a Local-First Nutrition Tracker

The original idea

What interested me most

How NutraFlux evolved

Why I made it local-first

What I learned from building it

1. A strong prompt is a good starting point — not a limitation

2. Product feel matters as much as base functionality

3. Privacy can be part of the product identity

4. Public repos raise the bar in a good way

Why I like building from prompts this way

Links

I Built a Free Hydration Tracker with No Signup: Here’s What I Learned

Why I built it

What Drink Daily is

What I wanted to get right

1. Simple

2. Lightweight

3. Polished

4. Actually usable

What I learned while building it

Product decisions matter as much as technical ones

Small UX details make a huge difference

Friction shows up fast in simple apps

Public projects feel different

What I’d improve next

Why I’m sharing it

Links