docs: rework README (pro layout, working badges incl. WIP status, links to CONFIG.md/demo/project, screenshot); drop broken Woodpecker badge + Vite template boilerplate
This commit is contained in:
reverse
parent
af252a8193
commit
ce37fe95aa
2 changed files with 113 additions and 74 deletions
187
README.md
187
README.md
|
|
@ -1,96 +1,135 @@
|
|||
# Orbit — a modern IRCv3 web client
|
||||
<div align="center">
|
||||
|
||||
[](https://ci.codeberg.org/repos/reversefr/orbit)
|
||||
<img src="public/orbit-icon.svg" width="92" height="92" alt="Orbit logo">
|
||||
|
||||
A bespoke, pluggable IRCv3 web client (TypeScript + React + Vite, zustand state).
|
||||
Powers [tchatou.fr](https://tchatou.fr), and re-pointable at any IRCv3 network
|
||||
via `config.json` — no rebuild needed.
|
||||
# Orbit
|
||||
|
||||
- **Dev:** `npm run dev` · **Build:** `npm run build` (→ `dist/`) · **Preview:** `npm run preview`
|
||||
- **Configuration:** runtime `config.json` (KiwiIRC-style) — re-point/re-brand
|
||||
without rebuilding. **See [CONFIG.md](./CONFIG.md)** for all options.
|
||||
- **Deploy:** copy `dist/*` (including `config.json`) to the web root served at
|
||||
`/app/`. To change config only, edit the deployed `/app/config.json` and reload
|
||||
(the service worker serves it network-first).
|
||||
**A modern, pluggable IRCv3 web client.**
|
||||
TypeScript · React · Vite · zustand — installable as a PWA, re-brandable without a rebuild.
|
||||
|
||||
[](#-status)
|
||||
[](./LICENSE)
|
||||
[](https://ircv3.net/)
|
||||
[](#-features)
|
||||
[](#)
|
||||
[](#-internationalization)
|
||||
|
||||
[**Live demo**](https://tchatou.fr/app/) · [**Project page**](https://orbit.tchatou.fr) · [**Configuration**](./CONFIG.md) · [**License**](./LICENSE)
|
||||
|
||||
<img src="docs/screenshot.png" width="820" alt="Orbit screenshot">
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## React + TypeScript + Vite (template notes)
|
||||
Orbit is a bespoke IRCv3 web client built from scratch — no KiwiIRC, 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](https://tchatou.fr)
|
||||
in production and can be re-pointed at **any** IRCv3 network and fully re-branded
|
||||
by editing a single runtime `config.json` — no rebuild required.
|
||||
|
||||
This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
|
||||
## 🚧 Status
|
||||
|
||||
Currently, two official plugins are available:
|
||||
> **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.
|
||||
|
||||
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
|
||||
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
|
||||
## ✨ Features
|
||||
|
||||
## React Compiler
|
||||
- **Real IRCv3** — negotiates [25 capabilities](#-ircv3-capabilities): chat history,
|
||||
message redaction (edit/delete), multiline, reactions, replies, account
|
||||
registration & SASL, server-time, away/typing, web push, and more.
|
||||
- **Rich composer** — bold/italic/underline + mIRC colours, emoji picker,
|
||||
`:emoji:` / `@nick` / `/command` tab-completion, multiline, image upload
|
||||
(paste & drag-drop), and per-channel drafts.
|
||||
- **Conversations** — channels & DMs, member list with roles, whois/profile
|
||||
panels, friends with online alerts, channel admin (modes, bans, topic),
|
||||
link/image/YouTube unfurling.
|
||||
- **Installable PWA** — 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/IRC mode.
|
||||
- **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](#-internationalization)).
|
||||
|
||||
The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
|
||||
## 🔌 IRCv3 capabilities
|
||||
|
||||
## Expanding the ESLint configuration
|
||||
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/irc/caps.ts`](./src/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.
|
||||
|
||||
If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
|
||||
## 🚀 Quick start
|
||||
|
||||
```js
|
||||
export default defineConfig([
|
||||
globalIgnores(['dist']),
|
||||
{
|
||||
files: ['**/*.{ts,tsx}'],
|
||||
extends: [
|
||||
// Other configs...
|
||||
Requirements: **Node 20+** and npm.
|
||||
|
||||
// Remove tseslint.configs.recommended and replace with this
|
||||
tseslint.configs.recommendedTypeChecked,
|
||||
// Alternatively, use this for stricter rules
|
||||
tseslint.configs.strictTypeChecked,
|
||||
// Optionally, add this for stylistic rules
|
||||
tseslint.configs.stylisticTypeChecked,
|
||||
|
||||
// Other configs...
|
||||
],
|
||||
languageOptions: {
|
||||
parserOptions: {
|
||||
project: ['./tsconfig.node.json', './tsconfig.app.json'],
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
},
|
||||
// other options...
|
||||
},
|
||||
},
|
||||
])
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
|
||||
## ⚙️ Configuration
|
||||
|
||||
```js
|
||||
// eslint.config.js
|
||||
import reactX from 'eslint-plugin-react-x'
|
||||
import reactDom from 'eslint-plugin-react-dom'
|
||||
Orbit is configured at **runtime** by `config.json` (KiwiIRC-style), 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).
|
||||
|
||||
export default defineConfig([
|
||||
globalIgnores(['dist']),
|
||||
{
|
||||
files: ['**/*.{ts,tsx}'],
|
||||
extends: [
|
||||
// Other configs...
|
||||
// Enable lint rules for React
|
||||
reactX.configs['recommended-typescript'],
|
||||
// Enable lint rules for React DOM
|
||||
reactDom.configs.recommended,
|
||||
],
|
||||
languageOptions: {
|
||||
parserOptions: {
|
||||
project: ['./tsconfig.node.json', './tsconfig.app.json'],
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
},
|
||||
// other options...
|
||||
},
|
||||
},
|
||||
])
|
||||
→ **See [CONFIG.md](./CONFIG.md)** for every option, merge rules, and examples.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"server": { "url": "wss://irc.example.org/ws/" },
|
||||
"startup": { "channels": ["#lobby", "#help"] },
|
||||
"branding": { "name": "ExampleChat", "url": "https://example.org" }
|
||||
}
|
||||
```
|
||||
|
||||
## License
|
||||
## 📦 Deployment
|
||||
|
||||
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](./LICENSE).
|
||||
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 [CONFIG.md → Deploy](./CONFIG.md#deploy).
|
||||
|
||||
## 🗂️ Project structure
|
||||
|
||||
```
|
||||
src/
|
||||
irc/ IRCv3 client, parser, capabilities, numerics, modes
|
||||
store.ts zustand store — connection, buffers, messages, actions
|
||||
components/ chat UI (sidebar, composer, message list, members, modals…)
|
||||
i18n/ react-i18next setup + 10 locale files
|
||||
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/i18n/locales/`](./src/i18n/locales).
|
||||
|
||||
## 🧪 Development & CI
|
||||
|
||||
A [Woodpecker CI](https://ci.codeberg.org) pipeline ([`.woodpecker.yml`](./.woodpecker.yml))
|
||||
runs **lint + test + build** on every push and pull request once the repository
|
||||
is enabled at [ci.codeberg.org](https://ci.codeberg.org).
|
||||
|
||||
## 📄 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](./LICENSE).
|
||||
|
||||
<div align="center"><sub>Built with React · IRCv3 — <a href="https://orbit.tchatou.fr">orbit.tchatou.fr</a></sub></div>
|
||||
|
|
|
|||
BIN
docs/screenshot.png
Normal file
BIN
docs/screenshot.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 932 KiB |
Loading…
Add table
Add a link
Reference in a new issue