Demo

These steps help you setup a NodeJS TypeScript backend server and a TypeScript React frontend from scratch. If already have these and simply want to add Krmx too them then follow the simple installation instructions.

Prerequisites

To be able to follow this demo you need the following tools installed on your system.

npm (recommended version 18.x or higher)
a code editor (such as Visual Studio Code or IntelliJ)
if your system doesn't have touch, then install it using npm install touch-cli -g

Note: This demo is created on a macOS system, but it is intended to be compatible with Linux or Windows systems.

Application Directory

First create a directory for our application.

mkdir my-first-krmx-app
cd my-first-krmx-app
 
# optional create a git repository for your application
git init

Create a Krmx server

Now, we're going to set up a NodeJS TypeScript server using the @krmx/server (opens in a new tab) reference implementation.

mkdir server
cd server
npm init -y
npm install --save-dev ts-node @types/node typescript nodemon
npm install @krmx/server
touch server.ts

Then, in your server/package.json add the following script. This script will start your server in dev mode. It will restart your server any time it detects changes to the server.ts file.

...
"scripts": {
  "dev": "nodemon --exec \"ts-node server.ts\" server.ts"
}
...

Then, add the following code to your server/server.ts file.

import { createServer, Props } from '@krmx/server';
 
const props: Props = { /* configure here */ }
const server = createServer(props);
 
server.on('join', (username) => {
  console.debug(`[debug] [my-app] ${username} joined!`);
});
server.on('message', (username, message) => {
  console.debug(`[debug] [my-app] ${username} sent ${message.type}`);
});
 
server.listen(8082);

Now start your server with npm run dev. Everytime you make changes to your server.ts file, the server will automatically reload.

If your server is up and running, Krmx clients should be able to connect using ws://localhost:8082 on your local machine.

If you would like to version control your application using git, then include the following .gitignore file in the server/ directory:

# in server/.gitignore
node_modules

To continue with the demo, you need to keep the server running. So before you continue, open a new terminal first.

Create a Krmx client

Next, we're going to set up a React client using the @krmx/client (opens in a new tab) reference implementation.

cd my-first-krmx-app
npx create-next-app client --use-npm --ts --src-dir --eslint --tailwind --app --import-alias '@/*'
cd client
npm install @krmx/client

Then, you can create a simple React client using the following setup in client/src/app/page.tsx.

"use client";
import { KrmxProvider, useKrmx } from '@krmx/client';
import { useState } from 'react';
 
export default function MyApp() {
  const [serverUrl] = useState('ws://localhost:8082');
  return (
    <KrmxProvider serverUrl={serverUrl} >
      <MyComponent/>
    </KrmxProvider>
  );
}
function MyComponent() {
  const { isConnected, isLinked, link, rejectionReason, send, leave, users, useMessages } = useKrmx();
  useMessages((message) => console.info(message), []);
  if (!isConnected) {
    // Your logic for when you're not connected to the server goes here
    return <p>No connection to the server...</p>;
  }
  if (!isLinked) {
    // Your logic for linking your connection with a user goes here
    return (
      <div>
        <button onClick={() => link('simon')}>Join!</button>
        {rejectionReason && <p>Rejected: {rejectionReason}</p>}
      </div>
    );
  }
  // Your logic for when you're ready to go goes here
  return (
    <div>
      <p>
        Welcome <strong>simon</strong>!
      </p>
      <button onClick={() => send({ type: 'custom/hello' })}>Send custom/hello</button>
      <button onClick={leave}>Leave</button>
      <h2>Users</h2>
      <ul>
        {Object.entries(users)
          .map(([otherUsername, { isLinked }]) => (
            <li key={otherUsername}>
              {isLinked ? '🟢' : '🔴'} {otherUsername}
            </li>)
          )}
      </ul>
    </div>
  );
}

Now you can run npm run dev in the client/ directory to start your client. Then, navigate to http://localhost:3000 to view the result. If your server is still running, you should be able to connect to it.

Next steps

After following this demo we recommend you to try the following.

Try and play around with what you have just created.
- How do you make sure that you can fill in your own name when joining?
- How to allow a maximum of 4 users on a server?
Look at some reference implementations.
Learn more about the Krmx server
Learn more about the Krmx client

Installation References