Live Sports Events | Websockets Course

Build this project step by step with our detailed tutorial on JavaScript Mastery YouTube. Join the JSM family!

📋 Table of Contents

1. ✨ Introduction
2. ⚙️ Tech Stack
3. 🔋 Features
4. 🤸 Quick Start
5. 🔗 Assets
6. 🚀 More

🚨 Tutorial

This repository contains the code corresponding to an in-depth tutorial available on our YouTube channel, JavaScript Mastery.

If you prefer visual learning, this is the perfect resource for you. Follow our tutorial to learn how to build projects like these step-by-step in a beginner-friendly manner!

✨ Introduction

Sportz is a comprehensive backend service designed for live sports coverage, utilizing REST endpoints for match and commentary management alongside WebSockets for real-time data broadcasting. The platform allows clients to monitor match lists and receive instantaneous score and play-by-play commentary updates through a robust streaming architecture that features heartbeats, rate limiting, and backpressure protection. By enforcing live-only updates and utilizing Zod schemas for strict input validation, Sportz ensures a reliable and structured flow of information; additionally, the service includes dedicated seeding tools to simulate live game environments and facilitate development.

If you're getting started and need assistance or face any bugs, join our active Discord community with over 50k+ members. It's a place where people help each other out.

⚙️ Tech Stack

• React is a declarative, component-based UI library that helps developers build interactive user interfaces with efficient rendering. It provides core primitives for state management, component lifecycle, and a virtual DOM, ensuring that applications remain performant, scalable, and easy to maintain across complex web environments.

• Arcjet is a security-first tool that helps developers protect their applications with just a few lines of code. It provides security primitives for rate limiting, bot protection, email validation, and sensitive data masking, ensuring the application remains secure and resilient.

• PostgreSQL is a powerful, open-source relational database system known for its reliability, data integrity, and robust feature set. It supports advanced data types, full ACID compliance, and extensibility, making it suitable for a wide range of applications.

• Drizzle ORM is a lightweight and performant TypeScript ORM designed with developer experience in mind. It provides a seamless interface between application code and database operations while maintaining high performance and reliability.

• Drizzle Kit is a CLI companion for Drizzle ORM that automates database migrations and schema synchronization; it ensures that your database structure remains consistent with your TypeScript definitions through efficient code generation.

• Node.js is an open-source, cross-platform JavaScript runtime environment that executes JavaScript code outside a web browser. It is designed to build scalable network applications and serves as the foundation for the project's backend logic.

• Express.js is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications. It facilitates the rapid development of RESTful APIs and serves as the standard server framework for the Node.js ecosystem.

• CORS Middleware is a package for Express that provides a simple mechanism to enable Cross-Origin Resource Sharing; it manages the security headers required to allow or restrict web applications from making requests to a different domain.

• Dotenv is a zero-dependency module that loads environment variables from a .env file into process.env; it helps keep configuration separate from code and secures sensitive credentials like API keys and database strings.

• WebSockets is a communication protocol that provides full-duplex communication channels over a single TCP connection; it enables real-time, bi-directional interaction between a client and a server without the overhead of traditional HTTP polling.

• WS Library is a simple-to-use, blazing-fast, and thoroughly tested WebSocket client and server implementation for Node.js; it serves as a high-performance foundation for building scalable real-time applications.

• Zod is a TypeScript-first schema declaration and validation library; it allows developers to define data structures and automatically infer types, ensuring that input data is strictly validated and type-safe at runtime.

Dev Tools

• CodeRabbit is an AI-powered code review platform that provides automated, contextual feedback on pull requests. It helps developers improve code quality and catch potential bugs early by integrating directly into the development workflow.

• Hostinger is a high-performance web hosting provider that offers scalable solutions for deploying web applications; it provides a user-friendly interface, optimized server performance, and robust security features to ensure reliable uptime and accessibility for your projects.

• Site24x7 is a comprehensive monitoring solution that provides deep insights into application performance and infrastructure health. It allows for real-time tracking of uptime, end-user experience, and server metrics to ensure maximum availability.

🔋 Features

👉 Match Management: Effortlessly list and create sports matches while maintaining accurate updates for scores and match statuses.

👉 Commentary Management: Access comprehensive play-by-play commentary tied to specific matches and add new entries to keep the coverage current.

👉 Real-Time Broadcasts: Deliver instant commentary and score updates via per-match WebSocket subscriptions, ensuring clients receive live data as it happens.

👉 WebSocket Protocol: Utilize a structured messaging system for subscribing, unsubscribing, and managing active subscriptions with automated ping responses.

👉 Robust WS Behavior: Maintain high performance and stability through the use of heartbeats, backpressure protection, rate limiting, and subscription caps.

👉 Input Validation: Ensure data integrity across both REST endpoints and WebSocket messages using strict Zod schemas.

👉 Seed Tooling: Rapidly populate matches and simulate live commentary and score changes with a dedicated script designed for testing and simulation.

And many more, including code architecture and reusability.

🤸 Quick Start

Follow these steps to set up the project locally on your machine.

Prerequisites

Make sure you have the following installed on your machine:

• Git
• Node.js
• npm (Node Package Manager)

Cloning the Repository

git clone [git remote URL]

Installation

Install the project dependencies using npm:

npm install

Set Up Environment Variables

Create a new file named .env in the root of your project and add the following content:

# Database
DATABASE_URL=

# Port & Host
PORT=8000
HOST=0.0.0.0 

# Arcjet
ARCJET_KEY=""
ARCJET_ENV="development"

# API URL
API_URL="http://localhost:8000"
# API_URL="YOUR_REAL_PRODUCTION_URL"

BROADCAST="1"
DELAY_MS="250"
MATCH_COUNT="0"

Replace the placeholder values with your real credentials. You can get these by signing up at: Example.

Running the Project

npm run dev

Open http://localhost:3000 in your browser to view the project.

Server runs at:

• HTTP: http://localhost:3000
• WS: ws://localhost:3000/ws

Scripts

• npm run dev — start server with watch mode
• npm run seed — seed DB with a basic match + commentary entry

REST API

List matches

GET /matches?limit=50

Create match

POST /matches

{
  "sport": "football",
  "homeTeam": "FC Neon",
  "awayTeam": "Drizzle United",
  "startTime": "2025-02-01T12:00:00.000Z",
  "endTime": "2025-02-01T13:45:00.000Z"
}

Allowed status values: scheduled, live, finished.

Status is computed from startTime and endTime.

List commentary for a match

GET /matches/:id/commentary?limit=100

Create commentary for a match

POST /matches/:id/commentary

{
  "minute": 42,
  "sequence": 120,
  "period": "2nd half",
  "eventType": "goal",
  "actor": "Alex Morgan",
  "team": "FC Neon",
  "message": "GOAL! Powerful finish from the edge of the box.",
  "metadata": { "assist": "Sam Kerr" },
  "tags": ["goal", "shot"]
}

WebSocket Protocol

Connect:

ws://localhost:3000/ws

Optional auto-subscribe on connect:

ws://localhost:3000/ws?matchId=123

Client → Server

{ "type": "subscribe", "matchId": 123 }

{ "type": "unsubscribe", "matchId": 123 }

{ "type": "setSubscriptions", "matchIds": [1, 2, 3] }

{ "type": "ping" }

Server → Client

{ "type": "welcome" }

{ "type": "subscribed", "matchId": 123 }

{ "type": "unsubscribed", "matchId": 123 }

{ "type": "subscriptions", "matchIds": [1, 2, 3] }

{ "type": "commentary", "data": { "id": 1, "matchId": 123, "message": "..." } }

{ "type": "pong" }

{
  "type": "error",
  "code": "match_not_found",
  "message": "Match 999 not found",
  "matchIds": [999]
}

Limits

• Max subscriptions per socket: 50
• Rate limit: 20 burst, 10 messages/sec
• Max message payload: 1 MB
• Backpressure: closes if buffered > 1 MB

Notes

• Auth is intentionally omitted to keep focus on WS mechanics.
• For multi-instance scaling, use pub/sub (Redis/NATS/Kafka) so broadcasts reach all WS servers.

🔗 Assets

Assets and snippets used in the project can be found in the video kit.

🚀 More

Advance your skills with JSM Pro Courses

Enjoyed creating this project? Dive deeper into our PRO courses for a richer learning adventure. They're packed with detailed explanations, cool features, and exercises to boost your skills. Give it a go!