Documentation · How it Works

What happens when a visitor lands on your page

A short tour of the Threadly architecture. If you’ve followed Getting Started and have comments on your page, you don’t need to read this — but it answers the inevitable “how does this actually work?” question.

Read time: ~3 minutes.

The data flow

widget.js is the same file for every site. It reads config off your <div>.
Widget calls the API for the site + thread, renders comments and the form.
Everything renders inside a Shadow DOM, so your CSS can’t break the widget and the widget can’t leak onto your page.

The full request path on a single page load:

// the request path

 your page  ─loads→  widget.js (Cloudflare Pages)
                        │ reads data-site / data-thread / data-api
                        ▼
                    Threadly API (the data-api URL)  ─→  database
                        │
                        ▼
              comments + a comment form, rendered into your <div>

Widget in the browser, API in front of the database. Same call from every site — yours just supplies the site + thread ids.

Keeping the widget updated

The widget URL is version-pinned on purpose:

widget URL

 https://threadly-widget.pages.dev/widget/0.5.4/widget.js

Your embed stays locked to that version forever, so a future change can’t silently break your page. Update by changing the number in the URL (e.g. 0.5.3 → 0.5.4) when you choose. The CDN always serves the exact bytes you pinned — no live edits.