TypeScript Tutorial: Building a Simple Command-Line Chat Application

Written by

learnmodernjavascript

in

Ever wanted to build your own chat application? It’s a fantastic way to learn about real-time communication, networking, and user interaction. While complex chat platforms involve intricate backend systems, databases, and security protocols, we can start with a simplified version right in your terminal using TypeScript. This tutorial will guide you through creating a basic command-line chat application, perfect for beginners and intermediate developers looking to expand their TypeScript skills.

Why Build a Command-Line Chat Application?

Command-line applications offer a unique learning experience. They force you to focus on the core logic and functionality without the complexities of a graphical user interface (GUI). Building a chat application in the terminal exposes you to crucial concepts like:

  • Networking: Understanding how to send and receive data over a network.
  • Real-time Communication: Implementing mechanisms for instant message delivery.
  • User Input and Output: Handling user interactions and displaying information in the console.
  • Concurrency: Managing multiple tasks simultaneously, such as sending and receiving messages.

This project will provide a solid foundation for more advanced projects involving real-time communication, such as web-based chat applications, online games, or collaborative tools. Plus, it’s a fun and engaging way to learn!

Prerequisites

Before we begin, ensure you have the following installed:

  • Node.js and npm: We’ll use Node.js to run our TypeScript code and npm (Node Package Manager) to manage dependencies. You can download them from https://nodejs.org/.
  • TypeScript: Install the TypeScript compiler globally using npm: npm install -g typescript.
  • A Text Editor or IDE: Choose your preferred code editor (VS Code, Sublime Text, Atom, etc.).

Project Setup

Let’s set up our project directory and initialize it:

  1. Create a Project Directory: Open your terminal and create a new directory for your project, for example, mkdir command-line-chat, then navigate into it: cd command-line-chat.
  2. Initialize npm: Run npm init -y to create a package.json file. This file will store your project’s metadata and dependencies.
  3. Initialize TypeScript: Run tsc --init to generate a tsconfig.json file. This file configures the TypeScript compiler. You can customize this file to adjust compilation settings. For this project, you can keep the default settings, but make sure the "module": "commonjs" and "target": "es2015" options are set.
  4. Install Dependencies: We’ll need a few dependencies to make our chat application work. Install them using npm:
npm install readline-sync ws

Here’s a breakdown of the dependencies:

  • readline-sync: This library allows us to easily read user input from the command line.
  • ws: This library provides a WebSocket implementation for real-time communication.

Core Concepts: WebSockets

WebSockets are the backbone of our chat application. They provide a persistent, two-way communication channel between the client (our command-line application) and the server. Unlike HTTP, which is stateless (each request is independent), WebSockets maintain a continuous connection, allowing for real-time data transfer.

Here’s how WebSockets work in a nutshell:

  1. Connection Establishment: The client initiates a WebSocket connection to the server.
  2. Persistent Connection: Once the connection is established, it remains open.
  3. Real-time Communication: Both the client and server can send messages to each other at any time.
  4. Data Transfer: Messages are sent and received in real-time.
  5. Connection Closure: The connection can be closed by either the client or the server.

Implementing the Chat Client (client.ts)

Let’s start by creating the client-side code. Create a file named client.ts in your project directory. This file will handle user input, connect to the server, and display messages.

// client.ts
import * as readlineSync from 'readline-sync';
import * as WebSocket from 'ws';

const serverUrl = 'ws://localhost:8080'; // Replace with your server address
const ws = new WebSocket(serverUrl);
let username: string;

ws.onopen = () => {
  console.log('Connected to the chat server!');
  username = readlineSync.question('Enter your username: ');
  ws.send(JSON.stringify({ type: 'setUsername', username: username }));
  // Start listening for messages after setting the username
  startListeningForMessages();
};

ws.onmessage = (event: WebSocket.MessageEvent) => {
  const message = JSON.parse(event.data as string);
  if (message.type === 'message') {
    console.log(`${message.username}: ${message.text}`);
  } else if (message.type === 'userList') {
    console.log(`Users online: ${message.users.join(', ')}`);
  } else if (message.type === 'serverMessage') {
    console.log(`Server: ${message.text}`);
  }
};

ws.onclose = () => {
  console.log('Disconnected from the chat server.');
};

ws.onerror = (error: WebSocket.ErrorEvent) => {
  console.error('WebSocket error:', error);
};

function startListeningForMessages() {
  const sendMessage = () => {
    const messageText = readlineSync.question(`${username}: `);
    if (messageText.trim() !== '') {
      ws.send(JSON.stringify({ type: 'message', username: username, text: messageText }));
    }
    sendMessage(); // Prompt for the next message
  };
  sendMessage(); // Start prompting for messages
}

Let’s break down this code:

  • Import Statements: We import readline-sync for user input and ws for WebSocket functionality.
  • Server URL: The serverUrl variable holds the address of our WebSocket server. Replace localhost:8080 with the actual address if your server runs on a different host or port.
  • WebSocket Initialization: We create a new WebSocket instance, connecting to the server.
  • onopen Event: This event fires when the connection to the server is successfully established. We prompt the user for a username and send it to the server. Then, we start listening for incoming messages.
  • onmessage Event: This event fires when the client receives a message from the server. We parse the message, check its type (e.g., “message”, “userList”, “serverMessage”), and display it in the console.
  • onclose Event: This event fires when the connection to the server is closed.
  • onerror Event: This event fires if any error occurs.
  • startListeningForMessages Function: This function prompts the user for input and sends messages to the server. It uses readline-sync to get input from the command line.

Implementing the Chat Server (server.ts)

Now, let’s create the server-side code. Create a file named server.ts in your project directory. This file will handle WebSocket connections, manage users, and broadcast messages.

// server.ts
import * as WebSocket from 'ws';

const wss = new WebSocket.Server({ port: 8080 });
const users: { [key: string]: WebSocket } = {};

wss.on('connection', ws => {
  console.log('Client connected');

  ws.on('message', message => {
    try {
      const parsedMessage = JSON.parse(message.toString());

      if (parsedMessage.type === 'setUsername') {
        const username = parsedMessage.username;
        if (username && !users[username]) {
          users[username] = ws;
          console.log(`${username} joined the chat`);
          // Send user list to all clients
          broadcastUserList();
          ws.send(JSON.stringify({ type: 'serverMessage', text: `Welcome, ${username}!` }));
        } else {
          ws.send(JSON.stringify({ type: 'serverMessage', text: 'Username already taken or invalid.' }));
        }
      } else if (parsedMessage.type === 'message') {
        const { username, text } = parsedMessage;
        console.log(`${username}: ${text}`);
        broadcastMessage(username, text);
      }
    } catch (error) {
      console.error('Error parsing message:', error);
    }
  });

  ws.on('close', () => {
    const username = Object.keys(users).find(key => users[key] === ws);
    if (username) {
      delete users[username];
      console.log(`${username} left the chat`);
      broadcastUserList();
    }
  });

  ws.on('error', error => {
    console.error('WebSocket error:', error);
  });
});

function broadcastMessage(username: string, text: string) {
  for (const user in users) {
    if (users.hasOwnProperty(user)) {
      users[user].send(JSON.stringify({ type: 'message', username, text }));
    }
  }
}

function broadcastUserList() {
  const userList = Object.keys(users);
  for (const user in users) {
    if (users.hasOwnProperty(user)) {
      users[user].send(JSON.stringify({ type: 'userList', users: userList }));
    }
  }
}

console.log('WebSocket server started on port 8080');

Here’s a breakdown of the server code:

  • Import Statement: We import the ws library.
  • WebSocket Server Initialization: We create a new WebSocket server, listening on port 8080.
  • connection Event: This event fires when a new client connects to the server.
  • message Event: This event fires when the server receives a message from a client. We parse the message and handle different message types:
    • setUsername: Sets the username for the client if it’s not already taken.
    • message: Broadcasts the message to all other connected clients.
  • close Event: This event fires when a client disconnects. We remove the user from the list of connected users and broadcast the updated user list.
  • error Event: This event fires if any error occurs.
  • broadcastMessage Function: This function sends a message to all connected clients.
  • broadcastUserList Function: This function sends an updated user list to all connected clients.

Running the Application

Now that we’ve written both the client and server code, let’s compile and run the application:

  1. Compile the TypeScript files: Open your terminal and navigate to your project directory. Run the following command to compile the TypeScript files into JavaScript:
tsc

This command will generate client.js and server.js files in your project directory.

  1. Run the server: Open a new terminal window or tab and navigate to your project directory. Run the server using Node.js:
node server.js

You should see a message in the console indicating that the server has started and is listening on port 8080.

  1. Run the client: In a separate terminal window or tab, navigate to your project directory and run the client:
node client.js

The client will prompt you to enter a username. Enter your desired username and press Enter. You’ll then be able to start typing and sending messages. Open multiple client instances in separate terminal windows to simulate multiple users.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • Server Not Running: Make sure the server is running before you start the client. If the server isn’t running, the client won’t be able to connect.
  • Incorrect Server Address: Double-check that the serverUrl in client.ts matches the address where your server is running (e.g., ws://localhost:8080).
  • Firewall Issues: Your firewall might be blocking the WebSocket connection. Ensure that port 8080 (or the port you’re using) is open.
  • Typos: Carefully check for typos in your code, especially in the import statements, variable names, and server address.
  • npm install Errors: If you encounter errors during the npm install step, make sure you have a stable internet connection and that the package names are correct. Sometimes, deleting the node_modules folder and running npm install again can resolve these issues.
  • Compilation Errors: If you get compilation errors from the TypeScript compiler (tsc), carefully review the error messages. They usually indicate syntax errors, type mismatches, or missing imports.

Enhancements and Next Steps

This is a basic command-line chat application. Here are some ideas for enhancements:

  • Private Messaging: Implement the ability to send private messages to specific users.
  • User List Display: Show a list of currently connected users in the client.
  • Message History: Store and display a limited history of messages.
  • Error Handling: Improve error handling and provide more informative error messages to the user.
  • Input Validation: Validate user input to prevent issues like empty messages or invalid usernames.
  • Command Support: Add commands like “/help” or “/nick” to change the user’s nickname.
  • GUI Client: Create a graphical user interface (GUI) for the chat application using a framework like React, Angular, or Vue.js.
  • Persistent Storage: Integrate a database to store messages and user information, making the chat history persistent.
  • Security: Implement authentication and authorization to secure the chat application. Consider using a library like jsonwebtoken for token-based authentication.

Key Takeaways

In this tutorial, you’ve learned how to:

  • Set up a TypeScript project with Node.js.
  • Use the ws library to create a WebSocket server.
  • Use the readline-sync library to handle user input.
  • Implement a basic command-line chat client and server.
  • Understand the fundamentals of real-time communication using WebSockets.

FAQ

  1. Why am I getting a “WebSocket connection failed” error?

    This error usually indicates a problem with the server address (serverUrl), the server not running, or a firewall issue. Double-check your server address, ensure the server is running, and verify that your firewall allows connections on the specified port.

  2. How can I deploy this chat application?

    You can deploy the server to a cloud platform like Heroku, AWS, or Google Cloud. You’ll need to configure the server to listen on the appropriate port and handle incoming WebSocket connections. For the client, you could create a simple web page that connects to the WebSocket server.

  3. Can I use this chat application in a production environment?

    This basic version is not production-ready. You would need to add security measures (authentication, authorization, input validation), handle errors more robustly, and potentially use a more scalable WebSocket server implementation for a production environment.

  4. How can I add user authentication?

    You would typically implement user authentication on the server-side. This could involve creating a user database, storing user credentials, and verifying user logins. You could use libraries like bcrypt for password hashing and jsonwebtoken for token-based authentication.

Building a command-line chat application in TypeScript is an excellent way to learn about networking and real-time communication. This project provides a solid foundation for more complex applications. By understanding the core concepts and building upon the provided code, you can create a robust and feature-rich chat application. Remember to experiment, explore the code, and try out different enhancements. The journey of building software is a continuous learning process, and each project provides new opportunities to improve your skills and understanding.

More posts