https://github.com/acarlson33/firepit
Realtime chat app, powered by appwrite. Easy to setup and deploy. Open source discord alternative
https://github.com/acarlson33/firepit
appwrite appwrite-auth appwrite-database appwrite-realtime appwrite-sites appwrite-storage bun chat-application chatapp chatapplication chatroom discord-clone nextjs partial-pre react reactjs server-side-rendering typescript
Last synced: 15 days ago
JSON representation
Realtime chat app, powered by appwrite. Easy to setup and deploy. Open source discord alternative
- Host: GitHub
- URL: https://github.com/acarlson33/firepit
- Owner: acarlson33
- License: gpl-3.0
- Created: 2025-10-11T19:53:53.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-07T23:55:13.000Z (17 days ago)
- Last Synced: 2026-03-08T04:51:45.488Z (17 days ago)
- Topics: appwrite, appwrite-auth, appwrite-database, appwrite-realtime, appwrite-sites, appwrite-storage, bun, chat-application, chatapp, chatapplication, chatroom, discord-clone, nextjs, partial-pre, react, reactjs, server-side-rendering, typescript
- Language: TypeScript
- Homepage:
- Size: 2.16 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# firepit
> **Version 1.0** - Production Ready 🎉
A modern, open-source chat platform inspired by Discord, built with Next.js 15, Appwrite, and TypeScript. Features real-time messaging, server organization, role-based permissions, and comprehensive moderation tools.
## Features
- **Server support** - support for servers like on discord
- **Server Invite System** - Create, manage, and use invite links with expiration and usage limits
- **Channel support** - support for channels like on discord
- **User profiles and status support** - missing external integration, but support for in app statuses and profiles
- **Emoji support** - Standard and custom emoji support with upload capabilities
- **Moderation** - Instance wide moderation and administration
- **Individual server moderation** - not currently supported, but will come in a later update with roles
## Codebase Features
- **Real-time Chat** - WebSocket-based messaging with typing indicators
- **Message Replies** - Reply to specific messages to maintain conversation context
- **Server & Channels** - Discord-like server organization with multiple channels
- **Server Invites** - Shareable invite links with expiration dates, usage limits, and revocation
- **Direct Messages** - Private conversations between users
- **User Status** - Online/offline presence with custom status messages
- **Emoji Support** - Standard emoji picker and custom emoji upload (up to 10MB)
- **Moderation Tools** - Soft delete, restore, and hard delete messages with full audit trails
- **Role-Based Access** - Admin, moderator, and user roles with granular permissions
- **User Profiles** - Customizable profiles with avatar support
- **TypeScript** - Full type safety across the entire codebase
- **Next.js 15** - App Router with React Server Components
- **TailwindCSS** - Modern, responsive UI design
- **shadcn/ui** - High-quality, accessible UI components
- **PWA Ready** - Progressive Web App support for mobile installation
- **Comprehensive Tests** - 1645 passing tests with extensive coverage
- **Production Ready** - Error boundaries, rate limiting, and security hardening
## 📋 Prerequisites
Before you begin, ensure you have:
- **Node.js 18+** or **Bun 1.2+** installed
- An **Appwrite instance** (cloud or self-hosted):
- Cloud: [appwrite.io](https://appwrite.io) (free tier available)
- Self-hosted: [Installation Guide](https://appwrite.io/docs/installation)
- **Git** for cloning the repository
## 🚀 Quick Start
```bash
# 1. Clone the repository
git clone https://github.com/your-org/firepit.git
cd firepit
# 2. Install dependencies
bun install
# 3. Set up environment variables
cp .env.local.example .env.local
nano .env.local # Edit with your Appwrite credentials
# 4. Validate your configuration
bun run validate-env
# 5. Initialize the database
bun run setup
# 6. Start the development server
bun dev # Uses Turbopack (~700x faster than Webpack)
```
Open [http://localhost:3000](http://localhost:3000) in your browser to see the application.
**Development Commands:**
- `bun dev` - Start with Turbopack (recommended, ~1.5s cold start)
- `bun dev:webpack` - Start with Webpack (fallback, ~12s cold start)
- `bun build` - Production build with Turbopack
- `bun build:webpack` - Production build with Webpack (fallback)
## 📚 Documentation
See the `/docs` folder for detailed guides:
- [Deployment Guide](./DEPLOYMENT.md) - Production deployment instructions
- [Performance Guide](./docs/PERFORMANCE.md) - Performance optimization details
- **[Performance Optimizations](./docs/PERFORMANCE_OPTIMIZATIONS.md) - NEW! First load time improvements**
- **[Performance Summary](./docs/PERFORMANCE_SUMMARY.md) - NEW! Quick reference guide**
- [Turbopack Configuration](./TURBOPACK_CONFIG.md) - Build tool configuration
- [Admin Guide](./docs/ADMIN_GUIDE.md) - Moderation and administration
- [Roles & Permissions](./docs/ROLES_AND_PERMISSIONS.md) - Permission system
- [New Relic Integration](./docs/NEW_RELIC.md) - APM and monitoring setup
- [Typing Indicators](./docs/TYPING_INDICATORS.md) - Real-time presence
- [Roadmap](./ROADMAP.md) - Planned features and timeline
- [Changelog](./CHANGELOG.md) - Version history and release notes
## 🚀 Production Deployment
Firepit is production-ready with:
✅ **Security Hardening**
- Global error boundaries
- Rate limiting on uploads and API endpoints
- Secure session management
- Input validation and sanitization
✅ **Performance Optimization**
- **90%+ improvement in first load times** (from 30+ seconds to 2-3 seconds)
- **85% faster First Contentful Paint** (8s → 0.8-1.2s)
- **50% smaller bundle size** (2.5MB → 800KB-1.2MB)
- Response compression (60-70% bandwidth reduction)
- Virtual scrolling for large lists
- Optimized bundle size with code splitting
- Partial Prerendering (PPR) for instant page loads
- Aggressive caching for repeat visits (~100ms)
✅ **Monitoring & Observability**
- New Relic APM integration
- Comprehensive error tracking
- Performance metrics
- Audit logging
✅ **Testing & Quality**
- 1644 passing tests
- Comprehensive test coverage
- Automated CI/CD pipeline
- Strict ESLint configuration
See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed production deployment instructions.
## ⚠️ Known Limitations
Version 1.3 does not include:
- Message threading (planned for v1.4)
- Message pinning (planned for v1.4)
- Voice/video calls (not currently planned)
- Native mobile apps (PWA supported)
See [ROADMAP.md](./ROADMAP.md) for the complete feature roadmap.
## 🤝 Contributing
We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
- Development workflow
- Code style guidelines
- Testing requirements
- Pull request process
- Issue reporting templates
## 🗂️ Project Structure
```
firepit/
├── src/
│ ├── app/ # Next.js app router pages
│ ├── components/ # React components
│ ├── lib/ # Utility functions and Appwrite integration
│ └── __tests__/ # Vitest test suites
├── scripts/
│ ├── setup-appwrite.ts # Database initialization script
│ └── validate-env.ts # Environment validation script
├── public/ # Static assets
├── DEPLOYMENT.md # Deployment documentation
└── .env.local.example # Environment variable template
```
## 🛠️ Available Scripts
| Command | Description |
| ----------------------- | -------------------------------------------- |
| `bun dev` | Start development server (with Turbopack) |
| `bun build` | Build for production |
| `bun start` | Start production server |
| `bun run test` | Run all tests with Vitest |
| `bun run test:coverage` | Run tests with coverage report |
| `bun lint` | Check code with ESLint |
| `bun lint:fix` | Fix auto-fixable linting issues |
| `bun validate-env` | Validate environment configuration |
| `bun setup` | Initialize Appwrite database and collections |
## 🔧 Configuration
### Environment Variables
The application requires several environment variables. Copy `.env.local.example` to `.env.local` and configure:
- `APPWRITE_ENDPOINT` - Your Appwrite API endpoint
- `APPWRITE_PROJECT_ID` - Your Appwrite project ID
- `APPWRITE_API_KEY` - Server-side API key with full permissions
For a complete list and detailed explanations, see [DEPLOYMENT.md](./DEPLOYMENT.md#2-environment-configuration).
### First-Time Setup
1. **Create an Appwrite account and project** at [appwrite.io](https://appwrite.io)
2. **Generate an API key** with required scopes (see DEPLOYMENT.md)
3. **Configure environment variables** in `.env.local`
4. **Run validation**: `bun run validate-env`
5. **Initialize database**: `bun run setup`
6. **Start the app**: `bun dev`
7. **Create your account** in the UI
8. **Make yourself admin** by setting `APPWRITE_ADMIN_USER_IDS` in `.env.local`
For detailed instructions, see [DEPLOYMENT.md](./DEPLOYMENT.md).
## 🐛 Troubleshooting
### Common Issues
- **"Appwrite endpoint not configured"** - Check your `.env.local` file exists and has the correct values
- **"Project not found"** - Verify your `APPWRITE_PROJECT_ID` matches your Appwrite Console
- **"Missing scope" errors** - Regenerate your API key with all required permissions
- **Setup script fails** - Ensure your API key has databases, collections, attributes, and indexes permissions
For more solutions, see [DEPLOYMENT.md - Troubleshooting](./DEPLOYMENT.md#troubleshooting).
## 🧪 Testing
This project maintains a comprehensive test suite with 100% pass rate:
```bash
# Run all tests
bun run test
# Run tests with coverage report
bun run test:coverage
# Run tests in watch mode (during development)
bun run test --watch
```
Current test coverage: **40.18%** statements (growing)
- 1645 tests passing across 115 test suites
- Comprehensive API route testing (44 new tests for invite system)
- Focus on security-critical modules (auth, roles, moderation), and modules critical for function (API routes, hooks, utility files, etc.)
## 📦 Deployment
### Vercel (Recommended)
1. Push your code to GitHub
2. Import project in [Vercel](https://vercel.com)
3. Add environment variables from `.env.local`
4. Deploy!
### Self-Hosted
```bash
# Build the application
bun build
# Start production server
bun start
```
For production deployment with Nginx, Docker, or other platforms, see [DEPLOYMENT.md - Production Deployment](./DEPLOYMENT.md#production-deployment).
## 🤝 Contributing
We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for:
- Development workflow
- Code style guidelines
- Testing requirements
- Pull request process
- Issue reporting templates
## 📄 License
firepit, a realtime chat app
Copyright (C) 2026 August (acarlson33)
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
Licensed under the GNU General Public License (GPL) v3.
You can find the License here: [License](./LICENSE)
## 🙏 Acknowledgments
Built with:
- [Next.js](https://nextjs.org/)
- [Appwrite](https://appwrite.io/)
- [TailwindCSS](https://tailwindcss.com/)
- [shadcn/ui](https://ui.shadcn.com/)
- [Vitest](https://vitest.dev/)
## 📧 Support
- **Documentation**: [DEPLOYMENT.md](./DEPLOYMENT.md)
- **Issues**: [GitHub Issues](https://github.com/your-org/firepit/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/firepit/discussions)