Getting started

Charcha puts comments on a static site without handing your readers’ data to anyone else. It runs as one Cloudflare Worker with one database, both sitting in your own Cloudflare account. You deploy it, you hold the rows, and there is no Charcha account anywhere in the picture.

Installing it takes three things: a deployment, one setting, and two lines of HTML.

Put it on a page

Paste these wherever the comments should appear. Most people put them at the bottom of a post template.

<div id="charcha"></div>
<script src="https://your-worker.workers.dev/embed.js" defer></script>

Swap in your own Worker’s address, the one Cloudflare gave you when you deployed. The script notices where it was served from, so you name your deployment once and the widget works out the rest.

That file is 8,242 bytes gzipped. It carries no framework and no Markdown parser, and Cloudflare serves it as a static asset, so fetching it never counts against your request budget. Loading the comments does.

Tell it your site is allowed

A fresh deployment trusts exactly one origin, its own. Until you add your site, browsers refuse every response and the widget sits there reporting that it could not load the comments.

Sign in at /admin on your Worker’s address, open Settings, and add your site’s origin. Include the scheme, leave off the trailing slash: https://yourblog.com, not yourblog.com/. If you write posts on your own machine, add http://localhost:4321 as well, or whatever port your generator uses.

Nearly everyone hits this once. Comments refusing to load, with the browser console complaining about CORS, is almost always this and nothing else.

Two things this list is not, both of which people reasonably assume it is. It is not what stops a script: the allowlist is a rule browsers enforce, so what it prevents is a page on somebody else’s site posting from one of your readers’ browsers. A program running on a server ignores it entirely, and the spam layers and your moderation queue are what deal with that. It is also not Turnstile’s hostname list, which governs where the bot check widget is allowed to render and has no effect here. The two are separate lists in separate places, and setting one does nothing for the other.

What a reader does

They type a name and a comment. Email is optional, never shown on the page, and only used if you turn on reply notifications later. There is no sign-up, no password, and nothing written to their browser, so somebody who comments on your site walks away leaving no trace of having been there.

Markdown works, though not all of it. Bold, italics, inline code, fenced blocks, links, blockquotes and bullet lists render. Headings, images and raw HTML do not. A comment box that accepts arbitrary HTML on somebody else’s page is an idea that has been tried enough times for the answer to be known.

Replies go one level and stop. A reader can reply to a comment but not to a reply. Threads nested four deep are unreadable on a phone, and the database refuses to create them regardless of what the page asks for.

Nothing appears until you approve it

Every comment from the public arrives held for review. Not flagged, not provisionally visible, simply not published. The person who wrote it sees their own comment with a note saying it is waiting. Nobody else sees anything.

You work through the queue at /admin. It is built for the keyboard, so a morning’s comments can be cleared without reaching for the mouse.

There is no setting to skip this. Publishing straight to the page from a public endpoint is how sites end up hosting other people’s link farms, and Charcha would rather make you click.

When something goes wrong

The widget tells your reader what happened instead of failing quietly. A comment that runs past the length limit says so. One the spam layers turn down says it could not be posted, without naming the check that caught it, since that explanation is really just instructions for the next attempt.

There is a stranger case worth knowing about. If the server accepts a comment but the widget cannot display it, the widget says exactly that and leaves the text sitting in the box. Posting again would send it twice, so it tells your reader that too rather than letting them guess.

Where to go next

Deploy covers the button, the two secrets it asks for during setup, and the optional pieces you can switch on afterwards. Theming has the class names and the three styling modes, including the one where Charcha ships no CSS at all and the appearance is entirely yours.

If you are trying to work out whether this will ever cost you money, Will this stay free? has the real numbers instead of a reassurance.