Introduction

Welcome to the Krmx documentation!

What is Krmx?

Krmx is a network protocol for realtime multi-user interactions.

Let's break that down.

Krmx is a network protocol. A network protocol defines a set of rules and conventions for exchanging messages between a client and a server. Krmx uses WebSockets to achieve realtime and bidirectional connections.

Krmx is a multi-user protocol. An application using Krmx always consists of one or more clients that create connections to a single server. Once a client established a connection to the server, it can link its connection to a user. Connections that are linked to users will receive realtime information about all users on the server and can send custom messages to the server.

Krmx lets you build interactions. As the application designer you extend the Krmx protocol with custom messages that are sent between server and client over the connections. These custom messages define the interactions your users have with the server (and each-other).

Getting Started Learn Krmx Krmx API TypeScript SDK reference

Quick Setup

In this example, we use the NodeJS Client and Server in TypeScript.

First create your Krmx Server (using npm install @krmx/server).

import { createServer } from '@krmx/server';
 
const server = createServer(/* configuration */);
server.on('message', (username, message) => {
  console.log(`Received a ${message.type} message from ${username}:`, message.payload);
});
 
const port = 12345;
await server.listen(port);

Then, you can create a Krmx Client using npm install @krmx/client.

import { createClient } from '@krmx/client';
 
const client = createClient(/* configuration */);
client.on('message', (message) => {
  console.log(`Received a ${message.type} message from the server:`, message.payload);
});
 
await client.connect('ws://localhost:12345');
await client.link('simon');
 
client.send({ type: 'chat', payload: 'Hello, World!' });

There are two client implementations available: a NodeJS Client (@krmx/client) and a React Client (@krmx/client-react). More information about the clients can be found in the Krmx API.

Krmx FAQ

The Krmx FAQ is a collection of useful questions and answers. If you have a question that isn't answered here, then please open an issue (opens in a new tab).

Why Krmx?

Krmx is the right solution if you're building a (web) application that is designed for users to interact with each other in realtime during a session. A great example of this is multiplayer (board)games, which is the use case around which Krmx was initially designed.

Where can I find examples?

When learning Krmx, it can help to take a look at some example projects. You can find examples in reference implementations.

Why are the Krmx reference implementations written in TypeScript?

Krmx provides reference implementations of its protocol. As the Krmx protocol is language agnostic, the reference implementations of the Krmx protocol could have been written in any language. So, why TypeScript?

Almost everyone has access to a browser and since WebSockets are supported by all major web browsers nowadays, we wanted to target browser based apps. Therefor the reference implementation of the client needs to be browser-based. As a result the client reference implementation has been written in TypeScript as that is the recommended language for the web.

For type reusability, simplicity and consistency with the client code, the server has also been written in TypeScript.

In theory, nothing is stopping you from using the Krmx protocol in another language. If you decide to build your own Krmx compatible implementation of a server or a client, then feel free to add that as a reference implementation to this repository by opening a pull request (opens in a new tab).

Does Krmx also allow me to manage state?

As Krmx primarily focuses on providing a protocol for communication between server and clients, it doesn't offer built-in state management capabilities. However, we've developed an extension called Krmx State to address this need.

Krmx State is a framework that extends Krmx by providing three robust state management models for your applications. You can easily integrate the Krmx State library in your Krmx based applications. This addition will enable you to create, update, and maintain shared state easily.

Terminology

name	description
krmx	the protocol used for realtime multi-user interactions
server	an application running a krmx server
client	an application (f.e. React App) that connects to a krmx server
connection	a websocket connection between a server and a client
user	an client controlled entity on the server that a connection can link to
(un)linking	the act of linking or unlinking a connection to or from a user
application	the complete system formed by a server and clients to serve interactive functionality

Authors

Simon Karman (opens in a new tab) - creator of Krmx

Installation