mountChat() options

mountChat() renders the chat into an element of your page and connects to the first server.

import 'bootstrap/dist/css/bootstrap.min.css';
import 'bootstrap-icons/font/bootstrap-icons.min.css';
import 'starchat/theme.css';
import { mountChat } from 'starchat';

const { connection, servers } = await mountChat('#chat', {
    primaryServer: 'irc.example.org',
    defaultChannel: '#lobby',
});

The first argument is a CSS selector or an element. Its content is replaced. The chat takes all the space the element gives it, so give the element a height or let it fill a flex container.

The returned promise resolves with the connection of the primary server and the list of servers offered in the login dialog. It rejects when the element is missing or no server could be resolved.

Options

Option Default Meaning
primaryServer Domain ('irc.example.org') or a full server list entry. Preselected in the login dialog. A domain that is not in the list becomes an entry of its own, its WebSocket address then comes from the discovery file.
serverList 'default' 'default' loads the public list, a URL loads your own list in the same format, false offers only the primary server.
defaultChannel Channel joined and shown after login. Only used on the primary server.
nickname Connect right away with this nick instead of showing the login dialog.
bearer Function that returns a login token, see Embedding with login.
modules all bundled Feature modules, for example [profilesModule] (exported by the package). A module only runs on servers that list its feature in the discovery file. Pass [] for a plain IRC client.
locale browser languages Language code or list of codes, for example 'de-DE'. The first one with bundled texts wins, English otherwise.
theme 'auto' 'auto' follows the system setting, 'dark' or 'light' fix it. Users can change it in the settings, their choice is kept in the browser.
overrides {} Texts that replace bundled ones, by key (see src/i18n/en.json).
appName 'StarChat' Name shown in texts that mention the app.
ctcpVersion 'StarChat' Answer to CTCP VERSION.
defaultQuitMessage Quit message until the user sets one.
Alpine bundled An Alpine.js instance your page already runs, for example from Livewire. Without it StarChat starts its own. Never run two.
onHostMessage (type, data) => {}. Messages from the chat for the page around it, for example unread counts.
pushWorker URL of the push service worker on your origin, see Push notifications. Without it there is no push in the browser.

Theme

starchat/theme.css contains the default theme for dark and light mode. It is built on Bootstrap 5 and Bootstrap Icons, both have to be loaded before it.

The colors are CSS custom properties on the chat element (--chat-bg, --chat-text, --chat-accent and so on, see src/ui/theme.css). Override them in your own stylesheet to change the look without touching the layout:

#chat {
    --chat-accent: #2e7d32;
    --chat-accent-hover: #256628;
}

The theme is set on the chat element only, so your page keeps its own color scheme.

Notification sound

The chat brings a few synthesized sounds. A site can add its own sound file, which is then offered first and used by default:

import { registerNotificationSound } from 'starchat';

registerNotificationSound('/sounds/ping.ogg');

Pass { makeDefault: false } to only add it to the list.

Push notifications

On networks with draft/webpush (Ergo, soju) logged-in users can get direct messages and mentions while the chat is closed. The browser needs a service worker on the origin of your page. Copy node_modules/starchat/src/push-sw.js (package path starchat/push-sw.js) to your public folder and pass its URL:

await mountChat('#chat', {
    primaryServer: 'irc.example.org',
    pushWorker: '/push-sw.js?name=MyNet&chat=/chat&icon=/icon.png',
});

The query string configures the worker:

Parameter Default Meaning
name StarChat Title of notifications without a sender.
chat / Path of the chat page. A tapped notification focuses a window under this path or opens it with ?open=<target>. Can be given more than once, the first is opened.
icon /favicon.ico Notification icon, a path on your origin.

The user turns push on under Settings → Notifications, which also asks for the browser permission. Muted channels and ignored users stay silent, the chat sends that list to the worker. Logging out unregisters the device.

No network API is needed for this. Only app builds (FCM) need the network's relay, the push feature of the discovery file.

Own commands

Slash commands are a plain object keyed by name. Add your own before mounting:

import { registerCommand } from 'starchat';

registerCommand('shrug', (args, ctx) => {
    ctx.sendOwnMessage(ctx.currentChannel, `${args.join(' ')} ¯\\_(ツ)_/¯`.trim());
});

An existing name is replaced. The built-in commands are listed in Commands and shortcuts.

Edit this page on GitHub