streamthing is a powerful streaming overlay and management system built for modern content creators. This self-hosted platform provides real-time Spotify integration, dynamic themes, song request management, and secure user authentication. Each deployment is designed for a single creator to ensure optimal security and performance.
🚀 Deploy for free: Use Vercel for hosting and Neon for PostgreSQL database - no credit card required!
- Real-time now playing overlays with customizable themes
- Dynamic CSS theming system with live editor and preview
- Track history logging with public API access
- Song request system with moderation tools
- JWT-based authentication with encrypted tokens
- Discord OAuth login with role-based permissions
- User management with moderator and ban capabilities
- Tamper-proof sessions - users cannot fake their identity
- Beautiful gradient design with React Icons
- Responsive layout that works on all devices
- Professional landing page for non-authenticated users
- Dark theme optimized for streaming
- Self-hosted architecture - each deployment for one creator
- HttpOnly cookies with secure JWT tokens
- Role-based access control for admin features
- Automatic token expiration and cleanup
- Authentication status and user information
- Quick access buttons to all features (role-based visibility)
- Version information with live git commit hash
- Beautiful landing page for non-authenticated users
- Secure logout functionality
- Real-time now playing display for OBS/streaming software
- Dynamic theme loading from database
- Resilient API handling with graceful error recovery
- Hover effects and smooth animations
- Customizable CSS for any streaming setup
- Live CSS editor with syntax highlighting
- Real-time preview of theme changes
- Multiple pre-built themes (neon, retro, minimalist, etc.)
- Save and activate themes instantly
- Theme management with create, edit, delete
- Public song request form for viewers
- Spotify URL validation and track info parsing
- User authentication required for requests
- Ban protection - banned users cannot submit
- Beautiful error handling and success messages
- Moderator-only access with role verification
- Review pending requests with full track info
- Approve or reject songs with one click
- Search and filter requests by title, artist, or user
- Real-time stats and queue management
- Admin-only user panel with search functionality
- Promote/demote moderators with role management
- Ban/unban users with instant effect
- User statistics and role overview
- Secure role updates with database persistence
All API routes use Next.js App Router with TypeScript and proper error handling.
GET /api/spotify/track- Current playing track (public)GET /api/spotify/track-logs- Track history with pagination- Query params:
limit,page,start,end(max 7 days)
- Query params:
GET /api/spotify/auth- Spotify OAuth login redirectGET /api/spotify/auth/callback- OAuth callback handlerPOST /api/spotify/submit-link- Submit song requestGET /api/spotify/requests- Get pending requests (mods only)PATCH /api/spotify/requests- Approve/reject requests (mods only)GET /api/spotify/themes- Get active theme CSSPOST /api/spotify/themes- Create/update themes (admin only)
GET /api/user- Current user info (JWT-secured)GET /api/discord/login- Discord OAuth loginGET /api/discord/callback- Discord OAuth callbackGET /api/discord/logout- Secure logout with token cleanupGET /api/users- List all users (admin only)GET /api/users/[id]/role- Get user role infoPATCH /api/users/[id]/role- Update user roles (admin only)
GET /api/twitch/auth- Twitch OAuth (placeholder)GET /api/twitch/callback- OAuth callback (placeholder)POST /api/twitch/webhook- Event webhooks (placeholder)GET /api/twitch/events- Recent events (placeholder)GET /api/twitch/status- Connection status (placeholder)
GET /api/version- Git commit hash and version info
Using Drizzle ORM with PostgreSQL for type-safe database operations:
track_logs- Spotify track historyid,track,artist,albumArt,duration,loggedAt
userRoles- User authentication and permissionsid,username,isModerator,isBanned
song_requests- Song request queueid,spotifyUri,title,artist,requestedBy,createdAt
spotify_themes- Dynamic CSS themesid,name,css,isActive,createdAt,updatedAt
- Type-safe queries with full TypeScript support
- Automatic migrations with
drizzle-kit - Connection pooling for optimal performance
- Prepared statements for security
- Next.js 15 - React framework with App Router
- React 19 - Latest React with modern features
- TypeScript - Type safety throughout
- Tailwind CSS - Utility-first styling
- React Icons - Professional icon library
- Next.js API Routes - Serverless functions
- Drizzle ORM - Type-safe database queries
- PostgreSQL - Robust relational database
- JWT - Secure token-based authentication
- Spotify Web API - Music data and authentication
- Discord API - User authentication via OAuth
- Twitch API - Future integration for stream events
- Vercel - Hosting and serverless functions (free tier)
- Neon - Serverless PostgreSQL (free tier)
- pnpm - Fast, disk space efficient package manager
- Fork this repository on GitHub
- Deploy to Vercel:
- Connect your GitHub account to Vercel
- Import your forked repository
- Vercel will automatically detect Next.js settings
- Set up Neon database:
- Create free account at neon.tech
- Create a new project and copy the connection string
- Configure environment variables in Vercel dashboard
- Set up Discord/Spotify apps (see setup section below)
- Node.js 20+
- pnpm 8+ (recommended) or npm/yarn
- PostgreSQL database (local or cloud)
-
Clone and install:
git clone https://github.com/oyuh/streamthing.git cd streamthing pnpm install -
Environment setup:
cp .env.local.example .env.local # Edit .env.local with your credentials (see section below) -
Database setup:
pnpm run db:push
-
Start development:
pnpm dev
-
Production build:
pnpm build pnpm start
Create .env.local from .env.local.example and configure:
# JWT secret for secure authentication (generate a long random string)
JWT_SECRET=your_super_secret_jwt_key_here
# Discord OAuth (create app at https://discord.com/developers/applications)
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
DISCORD_REDIRECT_URI=https://yourdomain.com/api/discord/callback# Spotify Web API (create app at https://developer.spotify.com/dashboard)
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
SPOTIFY_REDIRECT_URI=https://yourdomain.com/api/spotify/auth/callback
# Optional: Development access token for testing
DEV_SPOTIFY_ACCESS_TOKEN=your_dev_token_here# PostgreSQL connection string (Neon, Vercel Postgres, or self-hosted)
DATABASE_URL=postgres://username:password@host:port/database?sslmode=requireTWITCH_CLIENT_ID=your_twitch_client_id
TWITCH_CLIENT_SECRET=your_twitch_client_secret
TWITCH_REDIRECT_URI=https://yourdomain.com/api/twitch/callback
TWITCH_SECRET=webhook_secret_string# Your domain (for redirects and CORS)
NEXT_PUBLIC_SITE_URL=https://yourdomain.com- Go to Discord Developer Portal
- Create new application
- Go to OAuth2 → General
- Add redirect URL:
https://yourdomain.com/api/discord/callback - Copy Client ID and Client Secret
- Go to Spotify Dashboard
- Create new app
- Add redirect URL:
https://yourdomain.com/api/spotify/auth/callback - Copy Client ID and Client Secret
This project uses pnpm for better performance and disk efficiency.
- Windows: Run
migrate-to-pnpm.bat - macOS/Linux: Run
./migrate-to-pnpm.sh
# Install pnpm globally
npm install -g pnpm
# Clean npm artifacts
rm -rf node_modules package-lock.json
# Install with pnpm
pnpm install- Faster installs - Links packages instead of copying
- Disk space efficient - Shared package store
- Strict dependency resolution - Better security
- Lockfile consistency - Reliable builds
- JWT Authentication - Tamper-proof tokens with expiration
- HttpOnly Cookies - Protected from XSS attacks
- Role-based Access - Moderator and admin permissions
- CSRF Protection - Secure cookie settings
- Input Validation - Sanitized user inputs
- Rate Limiting - API abuse prevention (via Vercel)
- Spotify integration with real-time overlays
- Dynamic CSS theming system
- Song request management
- Secure JWT authentication
- User role management
- Beautiful modern UI
- Twitch integration - Events, chat commands, webhooks
- Advanced analytics - Play counts, user statistics
- Custom widgets - Follower goals, donation tracking
- Mobile app - React Native companion
- Plugin system - Third-party integrations
MIT License - see LICENSE file for details.
- Fork the repository
- Create feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open Pull Request
If streamthing helped your streaming setup, consider:
- ⭐ Starring the repository
- 🐛 Reporting bugs and issues
- 💡 Suggesting new features
- 🔗 Sharing with other creators
Built with ❤️ by Lawson Hart for the streaming community.