Skip to main content

​
Prerequisites

Before starting local development, ensure you have the following installed:
1

Node.js 20+

Watch N Chill requires Node.js 20 or later.
node --version
# Should output v20.x.x or higher
Download from nodejs.org or use a version manager like nvm.
2

Package Manager

Install either Bun (recommended) or use npm that comes with Node.js.Bun (recommended for faster installs):
curl -fsSL https://bun.sh/install | bash
npm is included with Node.js installation.
3

Redis

You need a Redis instance running. Choose one of these options:

​
Installation

1

Clone the Repository

git clone https://github.com/yourusername/watchnchill.git
cd watchnchill
2

Install Dependencies

bun install
3

Configure Environment

Create a .env.local file in the project root:
# Create environment file
touch .env.local
Add your configuration:
.env.local
# Redis connection (local Docker)
REDIS_URL=redis://localhost:6379

# Or Upstash Redis
# REDIS_URL=rediss://default:<password>@<subdomain>.upstash.io:6379
For local development, only REDIS_URL is required. Other variables have sensible defaults.
4

Start Development Server

bun run dev
You should see:
> Initializing Redis connection...
> Redis connected successfully
> Ready on http://localhost:3000
> Socket.IO server running on path: /api/socket/io
5

Open in Browser

Navigate to http://localhost:3000

​
Development Workflow

​
Hot Reload

The application uses tsx to run the custom server with hot reload:
  • Frontend changes: Next.js automatically reloads React components
  • Backend changes: tsx watches server.ts and backend files for changes
  • Socket.IO events: Restart the dev server to apply Socket.IO handler changes

​
Project Structure

watchnchill/
├── server.ts                 # Custom Next.js + Socket.IO server
├── src/
│   ├── app/                 # Next.js App Router pages
│   │   ├── (landing)/      # Landing page
│   │   └── room/[roomId]/  # Room page
│   ├── backend/
│   │   ├── socket/         # Socket.IO event handlers
│   │   ├── redis/          # Redis client and repositories
│   │   └── rate-limit.ts   # Rate limiting logic
│   ├── components/         # React components
│   ├── contexts/           # React contexts (Socket, Theme)
│   └── hooks/              # Custom React hooks
├── public/                  # Static assets
└── package.json

​
Available Scripts

# Start dev server with hot reload
bun run dev        # or: npm run dev

# Run linter
bun run lint       # or: npm run lint

# Format code with Prettier
bun run format     # or: npm run format

# Check formatting
bun run format:check

​
Redis Connection Verification

Verify your Redis connection is working: 
# Check if Redis container is running
docker ps | grep redis

# Test connection with redis-cli
docker exec -it watch-with-redis redis-cli ping
# Should output: PONG

​
Troubleshooting

​
Redis Connection Failed

If Redis is unavailable, the application will fall back to in-memory storage for rate limiting, but room state and chat will not persist.
Check Redis is running: 
# Docker
docker ps | grep redis

# Local service
redis-cli ping
Verify REDIS_URL: 
echo $REDIS_URL
# Should output: redis://localhost:6379

​
Port Already in Use

If port 3000 is already in use:
.env.local
PORT=3001
Then access the app at http://localhost:3001.

​
Socket.IO Connection Issues

If Socket.IO fails to connect:
  1. Check browser console for errors
  2. Verify Socket.IO path is correct: /api/socket/io
  3. Ensure no proxy/firewall is blocking WebSocket connections
  4. Check CORS settings (should auto-configure for localhost in dev)

​
Hot Reload Not Working

If changes aren’t being picked up: 
# Restart the dev server
# Press Ctrl+C and run:
bun run dev

​
Testing Your Changes

1

Create a Room

  1. Go to http://localhost:3000
  2. Click “Create Room”
  3. Copy the room ID and host token
2

Join from Another Tab

  1. Open a new incognito/private window
  2. Navigate to the same URL
  3. Click “Join Room” with the room ID
3

Test Real-time Features

  • Set a YouTube video URL as host
  • Play/pause/seek and verify sync across tabs
  • Send chat messages
  • Test typing indicators

​
Development Best Practices

  • Rate limiting is disabled in development mode for easier testing
  • CORS is auto-configured for localhost:3000 in development
  • Use browser DevTools Network tab to debug Socket.IO events
  • Check server console logs for backend debugging

​
Next Steps

Environment Variables

Learn about all available configuration options

Docker Setup

Run the full stack with Docker Compose

Production Deployment

Deploy to production platforms

Architecture

Understand the system architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us