js.org: a free .js.org subdomain for JavaScript projects on GitHub Pages

The problem js.org solves for JavaScript projects

A project page usually ends up at something like foo.github.io/bar or a long vendor URL. That is fine for a repository, but it is awkward on a conference slide, in a package README, or on a sticker. A registrar would sell you a short domain for a yearly fee, and you would then own DNS, renewal and the risk of forgetting to pay. js.org takes the other route: it keeps a shared domain and gives you one subdomain under it, for free, with no registrar account.

The README describes the service as dedicated to JavaScript and its community since 2015, and the donation badge says the money goes to registrar fees. So the model is a shared namespace funded by donations, administered by maintainers who review pull requests. That is the whole product. There is no control panel, no API to create a record, and no dashboard where you manage your entry.

It is for people who already have a site somewhere else and only need the name. If you need hosting, email, TLS certificates you control, or a domain you can transfer, js.org is the wrong layer. Note also that the repository does not carry a licence file among its top-level entries, so the terms that govern the service are the linked Terms and Conditions page rather than an open source licence.

How the subdomain list actually works

The mechanism is deliberately small. The repository contains cnames_active.js, a list of the subdomains that are currently served, plus ns_active.js and records_restricted.js for nameserver and restricted-record cases. To get a subdomain you add an entry to that list by pull request. The README says the new URL should go live within 24 hours and tells you to watch the pull request in case of a naming conflict or requested changes.

DNS itself is not run by the project. The README thanks Cloudflare for the DNS service that makes the offering possible, and states that js.org uses Cloudflare's free plan. So the data flow is: your site keeps its existing host, you set a custom domain there, the subdomain resolves through Cloudflare, and the entry in cnames_active.js is what makes the maintainers wire it up. The list is the source of truth for who is allowed to use a name.

That design has a consequence worth stating plainly. Your entry is a line in someone else's repository, and the namespace is shared. If two people want bar.js.org, one of them loses, and the README anticipates this by warning about naming conflicts. The wiki page on subdomain determination is where the project puts the guidance on picking a name, which suggests ambiguity is common enough to need a policy.

Installing js.org on a GitHub Pages site

There is nothing to install. The four steps in the README assume you already have a GitHub Pages site with reasonable content. First set up Pages, then decide the subdomain from your existing Pages URL: for http://foo.github.io/bar, either foo.js.org or bar.js.org is possible.

If you publish from a branch, add a file named CNAME in the branch that GitHub Pages serves, containing one line with the domain you chose.

foo.js.org

That single line is the file's entire content. If you publish with a GitHub Actions workflow instead, the README states that a CNAME file will not be processed, so you must add the custom domain through the repository settings under the Pages tab.

The last step is the pull request against this repository adding your subdomain to cnames_active.js. After that, the README says to expect the URL to go live within 24 hours. What you should see is your GitHub Pages site answering on the .js.org name; if the pull request stalls, the likely cause named in the README is a naming conflict or requested changes.

Using js.org with a host other than GitHub Pages

The README covers this case explicitly and it is the more interesting one, because it shows the service is not tied to GitHub's hosting. The requirement is that your hosting provider supports adding custom domains through a CNAME DNS record. If it does not, js.org cannot point at it.

You set up the site with whatever provider you use, pick the subdomain using the same username-or-repository logic, and follow the provider's instructions for a custom domain. The wiki keeps a list of hosts people have used successfully, with notes on configuring some of them, which is the practical reference here since provider UIs differ.

The final step is identical to the Pages path: a pull request adding your subdomain to cnames_active.js. The uniformity is a strength. Whether your site is a static build on GitHub or a documentation site on a commercial host, the review process and the entry format do not change. What does change is where you configure the domain, and the README does not try to abstract that away.

Content rules that disqualify more sites than people expect

This is the part most applicants skim. The README marks the content requirements as important and they are narrow. Websites must be directly related to the JavaScript ecosystem or community, with NPM packages and JS tools given as examples and personal pages or portfolios given as counterexamples. A site that merely uses JavaScript, without otherwise being related to the ecosystem, is not eligible. That single sentence rules out a large share of the sites people want a short domain for.

Three more rules follow. No placeholder pages: the site must contain substantive content relevant to its purpose. No automatic redirects away from the js.org domain, and redirects must require user interaction. No unrelated content, meaning the site has to stay focused on its stated topic. Read together, these rules mean js.org is not a URL shortener and not a vanity domain for a blog about something else.

The failure mode is a rejected or closed pull request after you have already configured your host. The README points to the full Terms and Conditions for the service, and those terms are the authoritative text, not the summary in the README. If your project is a commercial product that happens to be written in JavaScript, or a portfolio site for a developer who writes JavaScript, expect the review to stop there. The rules are about the ecosystem, not the language.

What you give up, and what to compare it against

The trade-off is control. You do not own the domain, you cannot move it to another registrar, and you cannot add arbitrary DNS records; records_restricted.js in the repository layout suggests some record types are handled separately or not at all. Your presence depends on an entry in cnames_active.js staying there, and on the project continuing to run its Cloudflare setup. The README frames the Cloudflare relationship as generous but informal, thanking them for flexible solutions and extended quotas on a free plan. That is not a service level agreement.

For a direct alternative, compare with buying your own domain from a registrar. With your own domain you control DNS, can add MX, TXT and wildcard records, can transfer the name, and can point it at any host without asking anyone. The cost is an annual fee and the administrative work of renewal. js.org inverts that: zero cost and no DNS administration, in exchange for a shared namespace and a review gate. If your site needs email on the same domain or a record type the project does not support, the registrar route is the one that works.

A second alternative is simply staying on the github.io URL or your provider's default subdomain. That costs nothing and requires no pull request. The reason to go through the js.org process anyway is the name itself: a short, ecosystem-branded address that reads well in a README badge or a talk slide. That is a presentation benefit, not a technical one, and it should be weighed as such.

Maintenance, review load and licence position

The repository shows no releases, so there is no version to track and nothing to upgrade. Your ongoing cost is the entry itself. If you rename your project, change hosts, or stop maintaining the site, the entry in cnames_active.js becomes stale, and the README gives no documented process for removing a subdomain or reclaiming one that has gone dead. That is a real gap: the documentation covers addition in detail and says nothing about rollback.

The maintenance burden sits with the maintainers, who review pull requests against a list that has been growing since 2015. For an applicant, the practical implication is that the 24 hour figure in the README is a target, and the README itself hedges by telling you to keep an eye on your pull request. Budget for a review cycle rather than an instant switch.

On licensing, the repository has no licence file among its top-level entries, so there is no open source licence to read here. The README directs users to the Terms and Conditions for the JS.ORG service, and those terms govern use of the subdomain. That is a service agreement, not a software licence, and it is the document to read before applying. Nothing in the README describes what happens to an entry if the service changes its DNS provider or its funding.

Editorial conclusion

Adopt js.org if you maintain a package, tool or documentation site that is directly part of the JavaScript ecosystem and you can point a CNAME at it. Do not apply if your site is a personal portfolio, a product that merely happens to use JavaScript, or a landing page that redirects elsewhere, because the content requirements rule those out. Before you open the pull request, verify that the subdomain you want is not already in cnames_active.js, that your host accepts a custom domain through a CNAME record, and that your CNAME file or Pages settings already point at the subdomain you are requesting.

Frequently asked questions

Official sources

1. Issues
2. js-org/js.org on GitHub
3. Project website
4. README