Orbit

A modern, pluggable IRCv3 web client. TypeScript · React · Vite · zustand. Installable as a PWA, re-brandable without a rebuild.

Live demo · Documentation · Project page · License

---

Orbit is a bespoke IRCv3 web client built from scratch, with no wrappers and no bridge. It speaks modern IRCv3 directly over a WebSocket and presents it as a polished, app-like chat experience: rich messages, reactions, replies, history, web push, themes and full internationalization. It powers tchatou.fr in production, and can be re-pointed at any IRCv3 network and fully re-branded by editing a single runtime config.json, with no rebuild required.

🚧 Status

Work in progress. Orbit is under active development. It runs in production, but the UI, config keys and internal APIs are still evolving and may change without notice between commits. Bug reports and contributions are welcome.

✨ Features

• Real IRCv3: negotiates 25 capabilities including chat history, message redaction (edit/delete), multiline, reactions, replies, account registration and SASL, server-time, away/typing and web push.
• Multi-network: connect to several IRC networks at once, each with its own buffers, identity and settings, and switch between them from the network bar.
• Rich composer: bold/italic/underline and mIRC colours, an emoji picker, :emoji: / @nick / /command tab-completion, multiline, image upload (paste and drag-drop), and per-channel drafts.
• Conversations: channels and DMs, a member list with roles, whois/profile panels, friends with online alerts, channel admin (modes, bans, topic), and link/image/YouTube unfurling.
• Installable PWA: an offline app shell via a service worker, plus Web Push notifications (RFC 8291 / VAPID) that work even when the app is closed.
• Themes: Light, Dark, Orbit, Orbit Dark, and a classic yomIRC skin (light and night).
• Settings that surface the protocol: a live Server panel (network, software, TLS, users, limits, raw ISUPPORT) and an IRCv3 panel showing exactly which capabilities your server supports.
• Fully internationalized: 10 languages, browser-detected and switchable live (see Internationalization).
• Plugins: an experimental, operator-controlled plugin API (window.Orbit) for events, IRC actions, theming and UI slots. See the plugin docs.

📚 Documentation

Full docs are hosted at orbit.tchatou.fr/docs:

Overview	what Orbit is, and why
Quick start	run your own in a minute
Configuration	every config.json option
Branding & themes	re-brand without a rebuild
Plugin system	the window.Orbit API
Compiled plugins	real React plugins
Build & deploy	self-hosting
IRCv3 capabilities	the protocol features
Architecture	how it's built

There's also a user wiki and an FAQ.

🔌 IRCv3 capabilities

Orbit requests every capability it knows how to use and lights up a live status panel (Settings → IRCv3) showing what the connected server actually supports. The full set it negotiates lives in src/core/irc/caps.ts, including draft/chathistory, draft/event-playback, draft/message-redaction, draft/multiline, draft/account-registration, draft/webpush, sasl, server-time, message-tags, echo-message, batch, labeled-response, multi-prefix, away-notify, chghost, and more.

🚀 Quick start

Requirements: Node 20+ and npm.

npm install
npm run dev        # Vite dev server with HMR
npm run build      # type-check (tsc -b) + production build → dist/
npm run preview    # serve the production build locally
npm run lint       # ESLint
npm run test       # Vitest unit tests
npm run test:e2e   # Playwright, drives the app against a real Ergo IRC server

⚙️ Configuration

Orbit is configured at runtime by config.json, fetched on startup and deep-merged over built-in defaults. Point it at another IRC network and fully re-brand it without rebuilding: just edit the deployed file and reload (the service worker serves it network-first).

→ Configuration docs cover every option, merge rules, and examples (source: CONFIG.md).

{
  "server":   { "url": "wss://irc.example.org/ws/" },
  "startup":  { "channels": ["#lobby", "#help"] },
  "branding": { "name": "ExampleChat", "url": "https://example.org" }
}

📦 Deployment

Static output: copy dist/* (including config.json) to the web root served at /app/. To change only the config later, edit the deployed /app/config.json and reload. Full steps in the Build & deploy guide.

🗂️ Project structure

src/
  core/
    irc/        IRCv3 client, parser, capabilities, numerics, modes
    store.ts    zustand store: connection, buffers, messages, actions
    store/      message handler, helpers, persistence
    services/   IRC services logic (NickServ/ChanServ routing, credential masking)
    networks.ts multi-network registry
    i18n/       react-i18next setup and 10 locale files
  components/   chat UI (sidebar, composer, message list, members, modals)
  modules/      the plugin system (the window.Orbit API and sandbox)
  platform/     browser services: notifications, web push, avatars
  themes/       theme stylesheets
  ui/ lib/      theming, formatting, editor helpers
public/         config.json, icons, manifest, service worker

🌍 Internationalization

Every user-facing string is translated across 10 languages: English, French, German, Spanish, Italian, Portuguese (Portugal & Brazil), Russian, Turkish and Nepali. The language is browser-detected, persisted, and switchable live from Settings. Strings live in src/core/i18n/locales/.

🧪 Development & CI

Every push runs the full gate before anything ships: lint (ESLint), unit tests (Vitest), end-to-end tests (Playwright driving the app against a real Ergo IRC server), then a production build. Nothing is deployed unless all of it passes. A Forgejo Actions workflow example lives in .forgejo/.

📄 License

Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0). If you run a modified version of Orbit as a network service, you must make your modified source available to its users. See LICENSE.

_{Built with React and modern IRCv3 · orbit.tchatou.fr}