@hathora/client-sdk

Hathora TypeScript Client SDK

The Hathora TypeScript Client SDK is used to connect your game or application to your Hathora server, and send / receive messages between the two.

• Installation
• Getting an APP_ID and APP_SECRET
• Establishing a connection
• Using the connection

Installation

Run the following from your client app's directory to install the SDK as an NPM dependency:

npm install @hathora/client-sdk

Getting an APP_ID and APP_SECRET

Visit console.hathora.dev and login if you haven't already done so.

You will be greeted with a project list screen, if you have already created an app the App ID and App Secret can be copied directly from the list...

If you have not yet created an app, click the Create Application button. You will then be faced with the following screen...

After entering a valid name and creating your application, it's App ID and App Secret will be available to be copied.

Establishing a connection

import { HathoraClient } from "@hathora/client-sdk";

async function establishConnection() {
  // Instantiate an object which represents our local connection info...
  const connectionInfo = {
    host: "localhost",
    port: 4000,
    transportType: "tcp" as const,
  };

  // Or pass undefined if working in a production Hathora environment
  // const connectionInfo = undefined;

  // Instantiate our client object (this is where you provide a valid Hathora APP_ID, which here is being passed via an environment variable)
  const client = new HathoraClient("YOUR_HATHORA_APP_ID", connectionInfo);

  // Use the client to get a token for the user
  const token = await client.loginAnonymous();

  // You can now create a new public room
  const newPublicRoomId = await client.createPublicLobby(token);

  // Or a new private room
  const newPrivateRoomId = await client.createPrivateLobby(token);

  // And query for existing public rooms
  const existingPublicRoomIds = await client.getPublicLobbies(token);

  // Create a HathoraConnection instance
  const connection = client.newConnection(newPublicRoomId);

  // Handle connection closing how you like
  connection.onClose((error) => {
    console.error("Connection closed", error);
  });

  // Initiate the connection
  connection.connect(token);

  // Return our connection to be used later...
  return connection;
}

Using the connection

// ...

async function example() {
  // Establish a Hathora connection (see above)
  const connection = await establishConnection();

  // Write JSON messages to the server
  connection.writeJson({
    type: 'test-message',
    value: 'Hello Hathora server!'
  });

  // Listen for JSON messages from the server
  connection.onMessageJson((json) => {
    // Handle the message in your app...
    console.log(json);
  });
}