cauenapier/TownSquare
cauenapier/TownSquare has 385 GitHub stars and 16 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-21 01:45 UTC. Last push 2026-11-16.
Progression mesurée des étoiles
- in 24h
- 0
- in 7 days
- Historique en cours
- in 15 days
- Historique en cours
- in 1 month
- Historique en cours
Variations nettes sur des périodes qui se chevauchent, pas des totaux quotidiens. Les mesures absentes restent vides. Les étoiles indiquent l’intérêt, pas la qualité.
À propos
TownSquare is an embeddable presence layer for websites. Visitors share a small scene, walk around, chat, and see who else is there. A single Node.js process can run one self-hosted scene or isolated scenes for registered sites.
Outils de développementREADME.md
OriginalTownSquare
TownSquare is an embeddable presence layer for websites. Visitors share a small scene, walk around, chat, and see who else is there. A single Node.js process can run one self-hosted scene or isolated scenes for registered sites.
The product contract lives in spec.md.
Run locally
TownSquare requires Node.js 18 or newer.
npm install
cp .env.example .env
npm start
Open http://127.0.0.1:8787. With the development tools enabled by the example
environment, /dev opens the crowd simulator and /walk-sandbox opens the
walk-cycle inspector. The health endpoint is /healthz.
npm start does not stop another process using the configured port. Use
npm run kill-port explicitly when that is what you want.
Repository map
server.js— HTTP routes, hosted APIs, WebSocket runtime, and scene state.server/— focused persistence, security, statistics, and plugin helpers.public/townsquare.mjs— stable widget mount API at/townsquare.mjs.public/widget/— widget behavior grouped by concern.public/lib/— canonical browser/Node-neutral protocol, scene, map, URL, and site-configuration modules. Both server and browser import these files.public/admin/hosted/— registration, site-admin, chat-admin, and service-admin pages.public/map/— public network-map layout and rendering.plugins/— trusted in-process feature plugins included in this distribution.scripts/— deployment, smoke tests, and visual regression helpers.ops/— example Nginx and systemd configuration.
The public landing page, user documentation, and changelog are maintained in the
separate TownSquare_landingpage repository. See
docs/architecture.md for the runtime boundaries.
Embed the widget
<link rel="stylesheet" href="https://townsquare.example/widget.css" />
<div id="townsquare-root" style="max-width:460px;margin-inline:auto"></div>
<script type="module">
import { mountTownSquare } from "https://townsquare.example/townsquare.mjs";
mountTownSquare(document.getElementById("townsquare-root"), {
serverOrigin: "https://townsquare.example",
socketPath: "/live",
theme: "host"
});
</script>
serverOrigin selects the HTTP and WebSocket service. socketPath defaults to
/live. A hosted multi-site embed also supplies its generated siteKey and
site-specific stylesheet; the registration page generates the complete snippet.
The host page owns placement. TownSquare owns everything inside
#townsquare-root. Palette tokens can be overridden by host CSS; the supported
tokens and defaults are defined in public/tokens.css and
public/lib/site-config-core.mjs.
The generated snippet gives the mount a centered max-width: 460px, which is a
good default for the widget's column layout. Hosts can choose another width;
test the installed page at its intended desktop and mobile sizes.
For a read-only presence pill ("5 people here", "2 on this page", or a short
"5 here"), use mountTownSquareCounter from /townsquare-counter.mjs.
Clicking it scrolls to a square mounted on the same page, otherwise opens
townSquareUrl. Its option contract is documented next to the
implementation in public/townsquare-counter.mjs.
For an emoji reactions bar (❤️ 👍 👏 …) with per-page counts, use
mountTownSquareReactions from /townsquare-reactions.mjs; options are
documented in public/townsquare-reactions.mjs.
Writes are accepted only from the site's allowed origins (or, self-hosted,
ALLOWED_ORIGINS) and counts are stored in DATA_DIR/reactions.json.
Both embeds can be restyled from the host page's CSS: class names, state
attributes, CSS variables, and recipes are in
docs/embed-styling.md.
Hosted operation
/registercreates a site key, install snippet, and private admin token./adminmanages a registered site's scene, appearance, connections, owner identity, moderation, counter, reactions, overlay, and enabled add-ons./service-adminmanages the service registry, aggregate activity, global map, and operator notifications whenSERVICE_ADMIN_PASSWORDis set./mapdisplays verified, enabled sites. The widget can also offer eligible sites as discovery destinations without exposing individual visitor activity.
Registered sites are stored under DATA_DIR (.data by default). Admin tokens
are stored as hashes. Runtime visitor and message state remains in memory.
Copy .env.example for the supported runtime settings and their
defaults. In production, set PUBLIC_ORIGIN, keep DATA_DIR on persistent
storage, and run behind a reverse proxy that supports WebSockets. The checked-in
Nginx examples include the expected /live limits and trusted client-IP setup.
Trusted server features compose through the in-process plugin contract described
in docs/plugins.md. There is no remote plugin loader.
Deploy
Docker:
docker build -t townsquare .
docker run --rm -p 8787:8787 townsquare
Release deployment is handled by scripts/deploy.sh. Run
scripts/deploy.sh --help for its current modes and environment contract; keep
real deployment values in the ignored .env.deploy.local file based on
.env.deploy.example.
Public-page design foundations live in public/design/. If the ignored local
scripts/admin/sync-design.js helper is present, use it after design changes to
check and sync the landing repository. The widget stylesheet remains independent.
Checks
npm run check # JavaScript syntax
npm run lint # ESLint
npm test # Node unit tests
npm run test:integration # real managed servers and WebSocket/API clients
npm run test:all # all of the above
The integration tests allocate their own ports and temporary data directories;
no manually started server is required. Browser-based geometry checks are
available as test:ground-line, test:widget-color, test:scene-alignment, and
test:discovery when Playwright browsers are installed.
License
MIT — see LICENSE.