TypeScript Tutorial: Creating a Real-Time Collaborative Whiteboard

Written by

learnmodernjavascript

in

In today’s interconnected world, the ability to collaborate in real-time is more important than ever. From brainstorming sessions to design reviews, shared digital spaces where multiple users can contribute simultaneously are becoming indispensable. This tutorial will guide you through building a real-time collaborative whiteboard application using TypeScript, providing a practical and engaging way to learn about WebSockets, backend integration, and state management.

Why Build a Collaborative Whiteboard?

Creating a collaborative whiteboard is an excellent project for several reasons:

  • Practical Application: It directly addresses a common need for real-time collaboration, making it relevant and useful.
  • Learning Opportunities: It provides hands-on experience with key technologies like WebSockets, which are essential for real-time applications.
  • Scalability: The concepts learned can be extended to other real-time applications such as chat apps, online games, and collaborative document editing.
  • Fun and Engaging: Building a visual application is often more engaging than working with purely textual data.

By the end of this tutorial, you’ll have a functional whiteboard application that allows multiple users to draw simultaneously, see each other’s drawings, and interact in real-time.

Prerequisites

Before we dive in, ensure you have the following:

  • Basic knowledge of JavaScript: Familiarity with variables, functions, objects, and the DOM is required.
  • Node.js and npm (or yarn) installed: These are needed to manage project dependencies.
  • A code editor: Visual Studio Code, Sublime Text, or any other editor of your choice.
  • TypeScript installed globally: You can install it using npm install -g typescript.
  • A basic understanding of HTML and CSS: While we won’t be focusing heavily on styling, some knowledge is necessary.

Project Setup

Let’s start by setting up our project. Create a new directory for your project and navigate into it using your terminal:

mkdir collaborative-whiteboard
cd collaborative-whiteboard

Initialize a new Node.js project:

npm init -y

Next, install the necessary dependencies. We’ll need:

  • typescript: For TypeScript compilation.
  • ws: For handling WebSockets on the server-side.
  • express: For creating a simple HTTP server (optional, but good for serving the frontend).
npm install typescript ws express --save

Create a tsconfig.json file to configure TypeScript compilation:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

This configuration sets the target to ES5 (for broader browser compatibility), specifies CommonJS modules, sets the output directory to dist, enables strict type checking, and enables ES module interop.

Create a src directory and within it, create three files:

  • index.html: The HTML file for the whiteboard interface.
  • server.ts: The server-side code (Node.js).
  • client.ts: The client-side code (TypeScript for the browser).

Building the Frontend (Client-Side)

Let’s start with the client-side code. Open src/index.html and add the following basic HTML structure:

<!DOCTYPE html>
<html>
<head>
  <title>Collaborative Whiteboard</title>
  <style>
    #whiteboard {
      border: 1px solid black;
      cursor: crosshair;
    }
  </style>
</head>
<body>
  <canvas id="whiteboard" width="800" height="600"></canvas>
  <script src="./client.js"></script>
</body>
</html>

This HTML sets up a basic canvas element, which we will use to draw on. We also include a basic style and a script tag that will load our compiled JavaScript file (client.js). Now, let’s create the client-side TypeScript code in src/client.ts:

// src/client.ts
const canvas = document.getElementById('whiteboard') as HTMLCanvasElement;
const ctx = canvas.getContext('2d')!;

// WebSocket connection
const ws = new WebSocket('ws://localhost:8080');

// Drawing state
let isDrawing = false;
let lastX = 0;
let lastY = 0;

// Event listeners for mouse events
canvas.addEventListener('mousedown', (e) => {
  isDrawing = true;
  [lastX, lastY] = [e.offsetX, e.offsetY];
});

canvas.addEventListener('mouseup', () => {
  isDrawing = false;
});

canvas.addEventListener('mouseout', () => {
  isDrawing = false;
});

canvas.addEventListener('mousemove', (e) => {
  if (!isDrawing) return;

  const x = e.offsetX;
  const y = e.offsetY;
  drawLine(lastX, lastY, x, y);
  sendDrawData(lastX, lastY, x, y);
  [lastX, lastY] = [x, y];
});

// Function to draw a line on the canvas
function drawLine(x1: number, y1: number, x2: number, y2: number) {
  ctx.beginPath();
  ctx.strokeStyle = 'black'; // Set line color
  ctx.lineWidth = 2; // Set line width
  ctx.moveTo(x1, y1);
  ctx.lineTo(x2, y2);
  ctx.stroke();
  ctx.closePath();
}

// Function to send drawing data to the server
function sendDrawData(x1: number, y1: number, x2: number, y2: number) {
  ws.send(JSON.stringify({ type: 'draw', x1, y1, x2, y2 }));
}

// WebSocket message handling
ws.addEventListener('open', () => {
  console.log('Connected to server');
});

ws.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'draw') {
    drawLine(data.x1, data.y1, data.x2, data.y2);
  }
});

Let’s break down this client-side code:

  • Canvas Setup: We get the canvas element and its 2D rendering context. The ‘!’ is a non-null assertion operator, telling TypeScript that we are sure the element exists.
  • WebSocket Connection: We establish a WebSocket connection to the server at ws://localhost:8080. This is where the real-time communication happens.
  • Drawing State: We use variables (isDrawing, lastX, lastY) to keep track of the drawing state.
  • Mouse Event Listeners: We add event listeners for mousedown, mouseup, mouseout, and mousemove to handle drawing events.
  • drawLine Function: This function draws a line on the canvas using the 2D rendering context.
  • sendDrawData Function: This function sends the drawing data (line coordinates) to the server via the WebSocket. The data is serialized to JSON.
  • WebSocket Message Handling: We handle incoming WebSocket messages. When the server sends a ‘draw’ message, we call the drawLine function to draw the line on the canvas.

Building the Backend (Server-Side)

Now, let’s build the server-side code in src/server.ts:

// src/server.ts
import { WebSocketServer, WebSocket } from 'ws';
import express from 'express';
import path from 'path';

const app = express();
const port = process.env.PORT || 8080;

// Serve static files (HTML, CSS, JS)
app.use(express.static(path.join(__dirname, '../')));

const server = app.listen(port, () => {
  console.log(`Server started on port ${port}`);
});

const wss = new WebSocketServer({ server });

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

  ws.on('message', message => {
    try {
      const data = JSON.parse(message.toString());
      if (data.type === 'draw') {
        // Broadcast draw data to all connected clients
        wss.clients.forEach(client => {
          if (client !== ws && client.readyState === WebSocket.OPEN) {
            client.send(JSON.stringify(data));
          }
        });
      }
    } catch (error) {
      console.error('Error parsing message:', error);
    }
  });

  ws.on('close', () => {
    console.log('Client disconnected');
  });
});

Let’s break down the server-side code:

  • Imports: We import the necessary modules: WebSocketServer and WebSocket from the ws package, express for creating an HTTP server, and path for handling file paths.
  • Express Server Setup: We create an Express application and define the port.
  • Serving Static Files: We use express.static to serve the index.html and the compiled JavaScript file (client.js) from the root directory.
  • WebSocket Server Setup: We create a WebSocket server, passing the HTTP server instance to it. This allows the WebSocket server to run on the same port as the HTTP server.
  • Connection Handler: The wss.on('connection') event handler is triggered when a client connects to the WebSocket server.
  • Message Handler: The ws.on('message') event handler is triggered when the server receives a message from a client. We parse the message (which should be JSON), and if it’s a ‘draw’ message, we broadcast it to all other connected clients.
  • Close Handler: The ws.on('close') event handler is triggered when a client disconnects.

Compiling and Running the Application

Now, let’s compile and run the application:

First, compile the TypeScript code using the TypeScript compiler:

tsc

This command will compile both client.ts and server.ts and put the compiled JavaScript files in the dist directory.

Then, start the server using Node.js:

node dist/server.js

Open your web browser and go to http://localhost:8080. You should see the whiteboard canvas. Open the same URL in another browser window or tab. Now, try drawing on one of the whiteboards; you should see the drawings appear on the other whiteboard in real-time!

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • WebSocket Connection Errors:
    • Problem: The WebSocket connection fails, and you see errors in the browser console.
    • Solution: Double-check the WebSocket URL in your client-side code (ws://localhost:8080). Ensure your server is running on the correct port and that there are no firewall issues blocking the connection.
  • Drawing Not Appearing:
    • Problem: You draw on one whiteboard, but it doesn’t appear on the other.
    • Solution: Check the server-side code to ensure that the server is correctly broadcasting the drawing data to all connected clients. Also, make sure that the client-side code is correctly receiving and interpreting the drawing data from the server. Verify that the WebSocket server is correctly configured to forward messages.
  • CORS Issues:
    • Problem: You might encounter CORS (Cross-Origin Resource Sharing) errors if your frontend and backend are running on different ports or domains.
    • Solution: If you are developing locally, you can use a CORS proxy or configure your server to handle CORS headers. For example, in your Express server, you could add middleware to handle CORS:
    // Add this to your server.ts
app.use((req, res, next) => {
  res.setHeader('Access-Control-Allow-Origin', '*'); // Allow requests from any origin (for development)
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
  next();
});
  • Typos:
    • Problem: Typos in variable names, function names, or property names can lead to unexpected behavior.
    • Solution: Use your code editor’s auto-completion and linting features to catch typos early. Carefully review your code for any potential errors.
  • Incorrect Data Serialization:
    • Problem: If you don’t serialize your data to JSON correctly before sending it over the WebSocket, it won’t be parsed correctly on the other end.
    • Solution: Ensure that you are using JSON.stringify() to serialize data before sending it and JSON.parse() to deserialize it when receiving it.

Enhancements and Next Steps

Once you have a working whiteboard, here are some ideas for enhancements:

  • Color Picker: Add a color picker to allow users to choose the color of their drawings.
  • Line Width Control: Allow users to adjust the line width.
  • Clear Canvas Button: Add a button to clear the entire canvas.
  • Undo/Redo Functionality: Implement undo and redo features to allow users to revert or reapply their actions. This can be done by storing the drawing history.
  • Shape Drawing: Allow users to draw shapes like rectangles, circles, and lines.
  • User Authentication: Implement user authentication to identify users and potentially save their drawings.
  • Error Handling: Implement robust error handling to gracefully handle connection issues, invalid data, and other potential problems.
  • Deployment: Deploy your application to a hosting platform like Heroku, Netlify, or AWS.

Summary / Key Takeaways

This tutorial provided a step-by-step guide to building a real-time collaborative whiteboard application using TypeScript, WebSockets, and a basic HTTP server. You learned how to set up the project, create the frontend and backend components, handle WebSocket connections, draw on a canvas, and synchronize drawings between multiple clients. You also gained insight into common mistakes and potential improvements. This project not only offers a practical and usable tool but also serves as a strong foundation for understanding real-time applications and further exploring web development with TypeScript.

FAQ

Q: What are WebSockets, and why are they used here?

A: WebSockets provide a full-duplex communication channel over a single TCP connection. Unlike HTTP, which is stateless and requires a new connection for each request, WebSockets allow for persistent connections, enabling real-time, two-way communication between the client and server. In this application, WebSockets are essential for sending drawing data from one client to the server and then broadcasting it to all other connected clients in real-time.

Q: Why is TypeScript used in this project?

A: TypeScript adds static typing to JavaScript, making code more maintainable, readable, and less prone to errors. It helps catch type-related errors during development, before the code is even run in the browser. Using TypeScript also improves code completion and refactoring capabilities in your code editor.

Q: How can I deploy this application?

A: You can deploy this application using various platforms, such as Heroku, Netlify, or AWS. You’ll need to package your frontend (HTML, CSS, JavaScript) and backend (Node.js server) and configure the hosting platform to serve the files and handle the WebSocket connections. The exact steps will depend on the platform you choose.

Q: What are some alternative libraries or frameworks I could use?

A: For the frontend, you could use a framework like React, Angular, or Vue.js to manage the UI. For the backend, you could use Socket.IO (which simplifies WebSocket handling), or other server-side frameworks like Koa or Fastify. These alternatives might provide additional features or abstractions that can streamline development, but the core concepts of WebSocket communication and real-time data synchronization would remain the same.

Building a real-time collaborative whiteboard is a great way to deepen your understanding of web development and explore the power of real-time communication. This project is a starting point, and the possibilities for enhancements and extensions are vast, allowing for further exploration and learning.

More posts