Desktop app

The desktop app lives in desktop/. It is an Electron shell around the chat: one tab per connection profile, IRC over TCP or WebSocket, chat logs on disk, notifications, a media player and updates. Each tab runs the chat page (desktop/chat/) in its own iframe and talks to the shell through postMessage.

Building

npm install
cd desktop
npm install
npm start            # development run
npm run dist -- --win    # installers in desktop/dist/ (also --linux, --mac)
npm test

npm start and npm run dist first run npm run prepare:app. It checks the edition, builds the chat page with Vite and writes everything the app needs to desktop/generated/.

Editions

Name, ids, icon, servers and texts of the app are set at build time by an edition. The bundled edition in desktop/edition/ builds StarChat. To build your own app, create a folder with an edition.json and your icon, and point the build to it:

node scripts/build.mjs dist --win --edition ../my-edition
STARCHAT_EDITION=editions/my-network npm run dist -- --linux

The edition is copied into the app package. Users cannot change it after the installation.

If you fork this repository, keep your edition in its own folder (for example desktop/editions/my-network/) instead of changing desktop/edition/, so merging upstream changes stays free of conflicts. In GitHub Actions, set the repository variable STARCHAT_EDITION to that folder.

edition.json

{
    "$schema": "../edition.schema.json",
    "appName": "Example Chat",
    "appId": "org.example.chat",
    "executableName": "example-chat",
    "icon": "icon.png",
    "chat": {
        "primaryServer": "irc.example.org",
        "defaultChannel": "#lobby"
    },
    "updates": { "provider": "github", "owner": "example", "repo": "example-chat" }
}
Field Required Meaning
appName yes Name in window titles, installers and chat texts (:app).
appId yes Reverse domain id, for example org.example.chat. Never change it after the first release.
executableName yes Name of the installers, the install folder and the Linux program: lower case letters, digits and -. On Windows and macOS the program is named after appName.
icon yes Square PNG with at least 512x512 pixels. The Windows and macOS icons are made from it.
dataDir no Folder in the user's app data, executableName by default.
formerDataDirs no Folders of older versions of your app. While dataDir does not exist, the first of these that exists is used, so profiles and logs stay.
publisher no Copyright and vendor in the installers.
splashImage no Image on the start screen, the icon by default.
chat.primaryServer no Domain of your network. The app then has a "Home Server" tab for new connections, starts with a connection to it, and takes login, API and features from its discovery file. Without it (the StarChat app) the user picks the first network from the directory or sets up a server, like in other desktop IRC clients.
chat.networkName no Name of the primary network in tabs and the connections list, the domain by default.
chat.serverList no Directory of networks for new connections: 'default' (the public list), an https URL of your own list, or false. The build bundles the list ('default': the version in this checkout, a URL: downloaded during the build), the app loads newer versions at runtime, so new networks need no app update.
chat.defaultChannel no Channel joined after login on the primary server.
chat.theme no auto, dark or light.
chat.themeCss no CSS file loaded after the bundled theme, see Theme.
chat.modules no Names of the feature modules to ship, all by default.
chat.ctcpVersion, chat.defaultQuitMessage no As in mountChat().
texts no Texts that replace bundled ones, per language: { "de": { "key": "Text" } }. Keys of the chat (src/i18n/) and of the app windows (desktop/locales/).
updates no Where the app looks for new versions: { "provider": "github", "owner", "repo" } or { "provider": "generic", "url" }. Without it the app does not update itself.
chatBundles no Signed chat updates without a new installer: { "manifestUrl", "publicKey" } (PEM file in the edition folder).

All file paths are relative to the edition folder and must stay inside it. The full schema is desktop/edition.schema.json.

Features of the primary server

Only for editions with chat.primaryServer. Some parts of the app need an API on the primary server and turn on only when its discovery file offers them. The Spotify link, for example, needs the feature spotify. Without a discovery file the app is a plain IRC client.

Connections

Each tab is a connection profile: the primary server of the edition (if it has one) or another server, over TCP (with or without TLS) or a secure WebSocket. TCP sockets are opened by the app, the chat page reaches them through nativeSocket (see mountChat() options). Profiles are managed under Settings, Connections. Passwords and tokens are stored encrypted with the system keychain (Electron safeStorage) and never shown again. They only go to the server they were stored for: a connection to the primary server remembers that server and its credentials are dropped when the edition names another one (older connections without it are bound on the first start), and changing the address of another connection, or switching TLS off, drops its stored password and token. "Remember me" in the login dialog keeps the API token of a password login for the next start.

Installed apps register as handler for irc:// and ircs:// links, for example ircs://irc.libera.chat:6697/#libera. A link to a server that has a connection opens its tab and the channel. Links to other servers open the dialog for a new connection with the server filled in, nothing connects without the user.

Chat updates without a new installer

With chatBundles in the edition, installed apps fetch a signed chat page from manifestUrl and use it from the next start. A chat that does not start within 20 seconds is dropped and the built-in one is used again. Updates that need a newer app (starchat.nativeApi in desktop/package.json) are skipped.

Create a key pair once and keep the private key secret:

openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt -out chat-signing-key.pem
openssl ec -in chat-signing-key.pem -pubout -out edition/chat-bundle-public.pem

Build and sign the chat page of your edition, then upload the folder so that manifest.json is reachable at manifestUrl:

cd desktop
npm run chat-bundle -- --key ../chat-signing-key.pem --out ../chat-update --edition editions/my-network

Releases

The workflow .github/workflows/desktop.yml builds Windows, Linux and macOS. A push to main replaces the installers on the pre-release latest-dev. A tag v* attaches installers and update files to the release of the tag, next to the web package. The builds are not signed yet, so Windows SmartScreen and macOS Gatekeeper warn on the first start.

Edit this page on GitHub