Skip to content
Projets

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.

Comment ces chiffres sont mesurés

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éveloppement

README.md

Original

TownSquare

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

  • /register creates a site key, install snippet, and private admin token.
  • /admin manages a registered site's scene, appearance, connections, owner identity, moderation, counter, reactions, overlay, and enabled add-ons.
  • /service-admin manages the service registry, aggregate activity, global map, and operator notifications when SERVICE_ADMIN_PASSWORD is set.
  • /map displays 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.