Skip to main content

​
Overview

This guide will help you set up Watch N Chill on your local machine and create your first watch party room. The entire process takes less than 5 minutes.
Watch N Chill uses a custom Next.js server that integrates Socket.IO for real-time features. Make sure you have Node.js 20+ and Redis installed before starting.

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 20 or higher is required. Download from nodejs.org

Redis

Either a local Redis instance or an Upstash Redis URL

​
Installing Redis

Choose one of the following options:

​
Installation

1

Clone the repository

First, clone the Watch N Chill repository:
git clone https://github.com/yourusername/watchnchill.git
cd watchnchill
2

Install dependencies

Install the required packages using your preferred package manager:
npm install
Bun is recommended for faster installation and build times, but any package manager works fine.
3

Configure environment variables

Create a .env.local file in the project root:
touch .env.local
Add your Redis connection URL:
.env.local
# Required: Redis connection string
REDIS_URL=redis://localhost:6379

# Optional: For production CORS (comma-separated)
# ALLOWED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com

REDIS_URL=redis://localhost:6379
If REDIS_URL is not set, the app defaults to redis://localhost:6379. Make sure your Redis server is running!
4

Start the development server

Run the custom Next.js server with Socket.IO:
npm run dev
You should see output similar to:
> Ready on http://localhost:3000
> Socket.IO server running on path: /api/socket/io

​
Create Your First Room

Now that Watch N Chill is running, let’s create your first watch party:
1

Open the application

Navigate to http://localhost:3000 in your browser. You’ll see the landing page with options to create or join a room.
2

Create a new room

  1. Click “Create Room” or navigate to /create
  2. Enter your display name (2-20 characters)
  3. Click “Create Room”
The app will:
  • Generate a unique 6-character room ID
  • Create a host token for you
  • Redirect you to the room at /room/[roomId]
// How room creation works behind the scenes
socket.emit('create-room', {
  hostName: 'Your Name'
});

socket.once('room-created', ({ roomId, hostToken }) => {
  // Room created! Navigate to /room/${roomId}
  console.log('Room ID:', roomId);        // e.g., "ABC123"
  console.log('Host Token:', hostToken);  // Stored in session
});
3

Add a YouTube video

As the host, you can add a video:
  1. Paste any YouTube URL in the video input field
  2. Supported formats:
    • https://www.youtube.com/watch?v=VIDEO_ID
    • https://youtu.be/VIDEO_ID
  3. The video will load for all participants automatically
Only hosts can change the video URL to prevent disruptions during the watch party.
4

Invite others to join

Share your room code with others:
  1. Copy the 6-character room ID from the URL or room header
  2. Friends can join by:
    • Clicking “Join Room” on the landing page
    • Entering the room code and their display name
    • Or navigating directly to /room/[roomId]
// How joining works
socket.emit('join-room', {
  roomId: 'ABC123',
  userName: 'Friend Name'
});

socket.once('room-joined', () => {
  // Successfully joined! Receive room state and sync video
});
5

Control playback

As the host, you control the video for everyone:
  • Play/Pause: Click the play button or press spacebar
  • Seek: Drag the progress bar or use arrow keys
  • Sync: All guests automatically sync every few seconds
The room uses Socket.IO events to synchronize state:
// Host controls trigger events
socket.emit('video-play', { roomId, currentTime });
socket.emit('video-pause', { roomId, currentTime });
socket.emit('video-seek', { roomId, currentTime });

// Guests receive and apply changes
socket.on('video-play', ({ currentTime }) => {
  player.playVideo();
  player.seekTo(currentTime);
});
6

Use the chat

Communicate with other viewers:
  1. Type your message in the chat input
  2. Press Enter to send
  3. See typing indicators when others are typing
  4. View the last 20 messages (persisted in Redis)
Click the fullscreen chat icon to expand chat on mobile or when you want to focus on the conversation.

​
Testing the Setup

Verify everything is working correctly:
Open your browser’s developer console. You should see:
Initializing socket...
Connecting to: http://localhost:3000
Socket connected: [socket-id]
If you see connection errors, verify:
  • Redis is running (redis-cli ping should return PONG)
  • REDIS_URL is correctly configured
  • Port 3000 is not in use by another application
Test your Redis connection:
redis-cli ping
Should return: PONGView stored room data:
redis-cli KEYS "room:*"
redis-cli SMEMBERS active-rooms
Create a room and check:
  • ✅ Redirected to /room/[roomId]
  • ✅ Room ID displayed in header
  • ✅ Your name appears in user list
  • ✅ You have the “Host” badge
  • ✅ Video input is enabled (host only)
Open the same room in two browser windows:
  1. Host window: Play/pause the video
  2. Guest window: Should sync automatically
  3. Host window: Seek to a different time
  4. Guest window: Should jump to the same time
If sync doesn’t work, check the browser console for Socket.IO errors and verify both windows are connected to the same room.

​
Running with Docker (Alternative)

Prefer to use Docker? Run both the app and Redis with Docker Compose: 
# Build and start containers
docker compose up --build
This uses the docker-compose.yml file which:
  • Builds the app image from the Dockerfile
  • Starts Redis on port 6380 (mapped from container port 6379)
  • Exposes the app on http://localhost:3000
  • Includes health checks for both services
docker-compose.yml
services:
  app:
    build: .
    ports:
      - '3000:3000'
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
      
  redis:
    image: redis:7-alpine
    ports:
      - '6380:6379'
    volumes:
      - redis_data:/data
The health check endpoint at /health is useful for monitoring in production deployments.

​
Common Issues

Solution:
  1. Verify Redis is running: 
    redis-cli ping
  2. Check your REDIS_URL in .env.local
  3. If using Docker, ensure the container is running: 
    docker ps | grep redis
Solution:
  1. Clear browser cache and hard reload (Cmd/Ctrl + Shift + R)
  2. Check if port 3000 is available: 
    lsof -i :3000
  3. Restart the development server
Solution:
  1. Check Redis is persisting data: 
    redis-cli KEYS "room:*"
  2. Verify the Socket.IO event listeners are registered
  3. Check browser console for error messages
Solution:
  1. Ensure both users are in the same room (check room ID)
  2. Verify Socket.IO is connected on both clients
  3. Check if one user is the host (only hosts can control playback)
  4. Look for network issues blocking WebSocket connections

​
Next Steps

Now that Watch N Chill is running, explore these topics:

Room Management

Learn about host promotion, room closing, and user management

Video Synchronization

Deep dive into how playback sync works

Chat System

Explore chat features, typing indicators, and message persistence

Deploy to Production

Deploy Watch N Chill to production with Docker and Upstash
Join our community to share feedback, report bugs, or contribute to the project!

Build docs developers (and LLMs) love

Get started for freeTalk to us