Install
Just use it
Open the web demo. It connects to ST-City and the channel #starchat by default. Under "Advanced settings" in the login dialog you can pick another network from the list or enter any domain.
Connecting shares your IP address with the network you choose, as with every IRC client.
Host the web client yourself
The web client is a static page. It needs no server of its own, any web host works (GitHub Pages, Cloudflare Pages, nginx, a shared host).
- Download
starchat-web-dev.zip(or.tar.gz) from the development build. After the first release it is on the releases page. - Unpack it and open
starchat-web/config.json. Set at least your network:
{
"primaryServer": "irc.example.org",
"defaultChannel": "#lobby",
"serverList": "default",
"appName": "Example Chat",
"links": [
{ "label": "Privacy", "url": "https://example.org/privacy" }
]
}
- Upload the folder to your web host, at the root of a domain or in a subfolder.
All keys of config.json are listed under Hosting the web client. Your IRC server has to accept WebSocket connections from the address of the page, see For network operators.
To build it yourself instead (Node.js 22.12 or newer): clone the repository, run npm install and npm run build:web. The page is in dist-web/, npm run web starts it locally.
Embed it in your site
If your site has its own build (Vite, webpack, Rollup), use StarChat as a library. Until the npm release, build it from the cloned repository with npm run build (output in dist/).
The chat needs Bootstrap 5 and Bootstrap Icons for its layout, plus its own theme:
import 'bootstrap/dist/css/bootstrap.min.css';
import 'bootstrap-icons/font/bootstrap-icons.min.css';
import 'starchat/theme.css';
import { mountChat } from 'starchat';
mountChat('#chat', {
primaryServer: 'irc.example.org',
defaultChannel: '#lobby',
});
The element #chat should have a fixed height or fill its container, the chat uses all space it gets. If your page already runs Alpine.js (for example through Livewire), pass it as Alpine so there is only one instance.
All options are listed under mountChat() options. To log in users of your site without the login dialog, see Embedding with login.
Desktop client
The desktop client is built with Electron and will be offered for Windows, Linux and macOS. It is being moved into the repository right now. Downloads will be on the releases page.
Make your network work with StarChat
Without any changes, StarChat works with your network on the desktop over TCP. For the web client a few more things are needed.
1. WebSocket endpoint
Browsers cannot open TCP connections, so the web client speaks IRC over WebSocket. Ergo, UnrealIRCd 6 and InspIRCd (module m_websocket) support this. Serve it over TLS (wss://), directly or behind a reverse proxy.
2. Allowed origins
Some servers only accept WebSocket connections from listed origins (in Ergo: server.websockets.allowed-origins). If you set such a list, add the origins of the pages your users chat from, for example https://getstarchat.net for the demo.
3. Discovery file (optional)
Serve https://<your-domain>/.well-known/starchat.json with the header Access-Control-Allow-Origin: *. The smallest useful file:
{
"schemaVersion": 1,
"name": "Example Network",
"websocketUrl": "wss://irc.example.org/webirc"
}
With it, users can type your domain and StarChat finds the WebSocket address. All fields are described under Discovery file.
4. Public server list (optional)
To show up in the network list of every StarChat, open a pull request that adds an entry to servers/servers.json. The format is described under Server list.