Today I'm writing about Krmx Starter, a feature rich starter for a Krmx application that uses React for the front end.

But, first! What is Krmx? Krmx is a real-time message broker that allows clients to connect to a server and exchange messages instantly. It has TypeScript implementations for both server and client. If you're new to Krmx, check out krmx.dev for the full documentation.

Why a Starter?

Krmx is just the foundation - it's not opinionated about how you use it. When starting a new project, it helps to have an opinionated starter that makes it easy to get going quickly. That's where this Krmx starter comes in.

What's Included

The starter gives you three main components:

• NodeJS TypeScript Krmx server - Handles the real-time connections and message routing
• TypeScript React / NextJS Krmx client - A modern frontend that connects to the server
• Shared code library - Common types and utilities used by both server and client

For details about all the included base functionality like linting, testing, and other development tools, see github.com/simonkarman/nodejs-backend-starter.

Krmx State Integration

The starter includes the experimental Krmx State library. This library is used for asynchronous state management over the Krmx protocol. Everything is fully type-safe. Krmx State comes with three state models (read more in the Krmx State documentation).

The shared code includes state models for four different examples. These examples are built into both the server and client code.

Getting Started

Clone the repository and run it locally:

git clone https://github.com/simonkarman/krmx-starter
cd krmx-starter
npm install
npm run dev
# Open your browser at http://localhost:3000

This starts the shared code, the server and the client in watch mode. When you make changes to any of those, everything restarts automatically.

What's Included?

Landing Page

The first thing a user sees is the landing/login page where users enter their username. Note that authentication is intentionally left out but can easily be added on the server side. For example, you could pass a JWT token to the Krmx link method from the client.

Users

Once connected to the server and linked to a user, the top part of the highlights which users are currently linked or unlinked to the server, giving you real-time visibility into who's online.

Chat System

The chat implementation uses Krmx to let users send messages to each other (messages are readable by the whole server). The chat includes events like when clients join or leave. All these modules in the starter are separate - you can remove or add them as needed.

Leave Confirmation

When a user wants to leave, a modal overlay appears asking for confirmation before disconnecting.

Dark Theme

The app includes a complete dark theme implementation alongside the default light theme.

Krmx State Examples

What is Krmx State?

Krmx State is a library for asynchronous state management over the Krmx protocol. It provides fully type-safe model definitions and usage in TypeScript. The library offers three models: atom, stream, and projection.

The starter includes an example for each model, plus a multi-model example where multiple models work together.

Atom Model Example

The atom screenshot shows a big number (99) on screen. This number syncs across all clients and increments every 2 seconds, plus whenever any client clicks it. The rotating background is just for aesthetics.

In the client code, this is simple:

const [counter, setCounter] = useAtom('my-counter', 0)

Optimistic Updates

All models use optimistic updates. Even though setting the counter requires a round trip to the server, the counter updates on the client immediately. If the server doesn't approve the change, it gets reverted on the client. This works the same for all three models.

Stream Model Example

The stream model screenshot demonstrates real-time data streams and event-driven state management for continuous data flow.

Projection Model Example

The projection screenshot shows a 52-card card game, demonstrating how derived state and complex transformations work for game logic.

Multi-Model Example

The multi-model screenshot displays a hexagon grid where clients can drag individual hexagons to different locations. While someone drags a hexagon, it becomes locked for other clients, showing how multiple state models work together.

Conclusion

The Krmx starter provides everything you need to build real-time, multi-user applications with modern TypeScript, React, and state management. Each component is modular, so you can customize it for your specific needs while keeping the real-time foundation solid.

Happy Coding!