You just have created a new JavaScript open source project. Now you wonder, how do I promote it? Having been devoted to open source for over a decade, I’d like to share how I usually approach it. Many of these ideas apply to not only JavaScript projects but also open source software projects in general.

There are 4 aspects to focus on:

  • Value Addition
  • High Code Quality
  • More Exposure to Potential Users
  • Lower Barrier to Use the Project

Value Addition

How is the project useful to the user? In what way does the project improve the user’s experience after adopting it?

To better understand the value added to the project, I found it helpful to create a mission statement for the project. As a rule of thumb, a mission statement can be used as the tagline of the homepage or README file of the project, and conveys the most essential message to your potential users in a few words.

For example, Docusaurus, a popular tool for generating documents, says on its homepage:

Build optimized websites quickly, focus on your content

It conveys the message that, using Docusaurus, the user can build optimized websites quickly without spending too much time worrying about website optimization, and therefore can focus on creating content.

High Code Quality

For an open source project to be widely adopted, high code quality is an indispensable attribute.

Not Buggy

It doesn’t need to be bug-free and hardly any non-trivial software is bug-free. However, it’s important to ensure that the user doesn’t run into bugs frequently. If you are not confident yet, it is usually a good idea to mark the project as in the alpha or beta stage for now.

Readable and Well-Commented

Readable and well-commented code not only helps with long-term code maintenance, but also gives users a good impression and attracts contributors. Users of open source software, especially those of libraries, frequently peek into their code. They may do so for many reasons, including:

  • Assessing whether the open source project is reliable and trustworthy.
  • Understanding how the project works, e.g., to figure out whether a library is compatible with their project.

More Exposure to Potential Users

Build a Website

We believe it’s important to have a website for an open source project, even a simple one. Having a website, preferably with a custom domain, has a few benefits over a GitHub (or GitLab or any other code hosting website) project page as homepage:

  • A website gives the audience a sense of trust. The audience is more likely to see the project being taken seriously by its maintainers, rather than some random code dropped to a code hosting website.
  • A website is more flexible. If you decide to move your project to another code hosting website, people can still access your project from the same URL, and all links to the project website remain valid. Don’t think you’ll ever move to another code hosting website? Consider the massive movement from SourceForge to GitHub that happened in the past.
  • Your domain builds authority from search engines. It makes promoting future open source projects easier if you host it under the same domain, because search engines are likely to rank your next project homepage higher.

Plus, it’s really straightforward to create that website. All mainstream code hosting websites provide automatic website building. (Instructions from GitHub, GitLab, and BitBucket.)

Social Media

Spreading words on social media can gain more exposure for the project. This goes beyond just posting a link to the project on X or Mastodon. It is important to interact with users from relevant communities.

For example, if the project is a plugin for Software X, consider posting to relevant user forums or mailing lists of Software X. If the project solves a particular problem for a specific community, consider posting to forums and mailing lists of that community.

Depending on the project, it is often possible to seek links to the project from more established projects. Overall, the link should be a win-win for both projects and, if applicable, I would try to convince the maintainers of an established project why the link brings them benefits.

For example, we have developed React-AutoNumeric, React components based on AutoNumeric. We opened a pull request to add a link to the project from AutoNumeric’s Related Projects page, and explained that the current linked React component project on their website no longer supported the current version.

If you have the budget, paid ads may also work, despite being not commonly employed by open source projects. How to allocate a budget for paid ads is beyond the scope of this post. You may refer to a paid ads-focusing article if you intend to go down this route.

Lower Barrier to Use the Project

Good Documentation

Good documentation is key to lowering the barrier for the users of your project. While you, as the developer, are already familiar with the project and its context, your potential users are not. A good document should include the following:

  • Document for each feature.
  • Document for a quick start.
  • API document if it’s a library or supports plugins.
  • (Optional) Internal documentation. However, your code comment may be sufficient.

Packaging and Distribution

Depending on the nature of your project, making it available in the appropriate forms of packages and distribution channels is important.

Npm Package

If your project is a library, it is usually crucial to publish the project to the public npm registry. Even for non-library projects, it provides one more channel for your users to install the software, which many tech-savvy users prefer.

Relevant App Stores

Publishing in relevant app stores makes it easier to install your project. What app stores are relevant depends on the nature of the project. For example, normally an Android app facing the North American market should publish in Google Play Store and Amazon Appstore.

One common mistake is to publish only in the largest relevant app store. However, often a large percentage of users prefer or are stuck with another app store. For example, if you’ve built a browser extension, it is important to publish it in all applicable major browser extension stores. This means not only Chrome Web Store, but also Add-ons for Firefox, Edge Add-ons, and Opera addons, if applicable.

Downloadable Pre-built Binaries

Downloadable pre-built binaries are convenient for users in many situations:

  • GUI applications. You can create the pre-built binaries using Electron, Tauri, or other toolkits.
  • Command line programs that target communities beyond JavaScript developers. While most JavaScript developers are familiar with npm, most non-JavaScript developers are likely not. You can create a pre-built binary using Node.js, Deno, or Bun.

Conclusion

We discussed how to promote JavaScript open source projects. We discussed 4 aspects:

  • Value Addition
  • High Code Quality
  • More Exposure to Potential Users
  • Lower Barrier to Use the Project