Skip to main content

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 20+ installed (download)
  • npm, yarn, pnpm, or bun package manager
  • Upstash account for Redis and Realtime (sign up free)

​
Setup Upstash services

1

Create Redis database

  1. Log in to Upstash Console
  2. Navigate to Redis section
  3. Click Create Database
  4. Choose a name and region (any region works)
  5. Copy the UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN
2

Create Realtime instance

  1. In Upstash Console, go to Realtime section
  2. Click Create Realtime
  3. The Realtime instance will automatically connect to your Redis database
  4. No additional configuration needed - it uses the same Redis credentials
Upstash Realtime automatically uses your Redis credentials. You only need to configure Redis environment variables.

​
Install locally

1

Clone the repository

git clone https://github.com/shehryaraijaz/realtime-chat-next.git
cd realtime-chat-next
2

Install dependencies

npm install
3

Configure environment variables

Create a .env.local file in the project root:
.env.local
UPSTASH_REDIS_REST_URL="https://your-instance.upstash.io"
UPSTASH_REDIS_REST_TOKEN="your-token-here"
Never commit .env.local to version control. Add it to .gitignore.
4

Start the development server

npm run dev
The application will start at http://localhost:3000

​
Test the application

1

Create your first room

  1. Open http://localhost:3000
  2. You’ll see an auto-generated username (e.g., user_a8f9d2)
  3. Click CREATE ROOM
  4. You’ll be redirected to a new room with a unique ID
2

Invite someone to join

  1. Copy the room URL from your browser
  2. Open it in an incognito window or another browser
  3. Each participant gets a unique username
  4. The 10-minute countdown timer starts when the room is created
3

Send messages

  1. Type a message in the input field
  2. Press Enter or click SEND
  3. Messages appear instantly for all connected participants
  4. Your messages show in green, others in blue
4

Test self-destruction

Watch the countdown timer in the header:
  • Timer shows 10:00 when room is created
  • Turns red when less than 60 seconds remain
  • Click DESTROY NOW to manually destroy the room
  • All participants are redirected when room is destroyed

​
Verify real-time functionality

Open the room URL in multiple browser tabs to see real-time synchronization in action.
You should observe:
  1. Instant message delivery - Messages appear immediately in all tabs
  2. Synchronized destruction - All tabs redirect when room is destroyed
  3. Countdown sync - All participants see the same countdown timer

​
Common issues

The room may have expired after 10 minutes. Create a new room to continue.
  • Verify Upstash Redis credentials in .env.local
  • Check browser console for WebSocket connection errors
  • Ensure Realtime is enabled in your Upstash console
Clear your browser cookies and refresh. Authentication tokens are stored as cookies and may need to be reset.
Run on a different port:
PORT=3001 npm run dev

​
Project structure

Key files and directories: 
realtime-chat-next/
├── src/
│   ├── app/
│   │   ├── page.tsx              # Lobby - create/join rooms
│   │   ├── room/[roomId]/        # Chat room interface
│   │   └── api/                  # API routes
│   ├── lib/
│   │   ├── redis.ts              # Redis client configuration
│   │   ├── realtime.ts           # Realtime schema definition
│   │   └── realtime-client.ts    # Client-side WebSocket hook
│   └── types/
│       └── message.ts            # Message type definitions
├── package.json
└── .env.local                     # Your environment variables

​
Next steps

How it works

Learn about the architecture and core concepts

Deploy to Vercel

Launch your instance to production

API reference

Explore the REST API endpoints

Redis data model

Understand how data is stored and expires

Build docs developers (and LLMs) love

Get started for freeTalk to us